Exemplos em PHP
Setup
composer require guzzlehttp/guzzle vlucas/phpdotenvMYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/restMYSE_API_TOKEN=seu_token_aquiCliente HTTP centralizado
<?phpnamespace App;
use GuzzleHttp\Client;use GuzzleHttp\Exception\RequestException;
class ApiError extends \Exception{ public function __construct( public int $httpStatus, string $message, public mixed $payload = null, public ?string $requestId = null ) { parent::__construct($message); }}
class MyseApi{ private Client $client;
public function __construct() { $this->client = new Client([ // A barra final é obrigatória: sem ela o Guzzle descarta o "/rest" ao resolver o path 'base_uri' => rtrim($_ENV['MYSE_API_BASE'], '/') . '/', 'timeout' => 30, 'headers' => [ 'Authorization' => 'Token ' . $_ENV['MYSE_API_TOKEN'], 'Content-Type' => 'application/json', ], 'http_errors' => false, ]); }
public function call(string $method, string $path, ?array $body = null, ?float $timeout = null): array { $options = $body ? ['json' => $body] : []; if ($timeout !== null) { $options['timeout'] = $timeout; // sobrescreve os 30 s do cliente nesta chamada } $res = $this->client->request($method, ltrim($path, '/'), $options);
$requestId = $res->getHeaderLine('X-Request-Id') ?: null; $bodyStr = (string) $res->getBody(); $json = json_decode($bodyStr, true) ?? [];
// Erro HTTP duro if ($res->getStatusCode() >= 400) { throw new ApiError( $res->getStatusCode(), $json['error']['message'] ?? "HTTP {$res->getStatusCode()}", $json, $requestId ); }
// Erro de domínio if (($json['status'] ?? null) === '999') { throw new ApiError( 200, $json['data']['erro'] ?? $json['descricao'] ?? 'erro', $json, $json['meta']['request_id'] ?? $requestId ); }
return $json; }}Cenário: emitir NFCe com polling
<?phpfunction emitirNFCe(MyseApi $api, array $pedido): array{ $body = [ 'serie' => '65', 'cfop' => '5102', 'numero-origem' => 'PED-' . $pedido['id'], 'tp_pagamento' => $pedido['forma_pagamento'], 'cliente' => $pedido['cpf_cnpj_cliente'], 'itens' => array_map(fn($i) => [ 'produto' => $i['sku'], 'quantidade' => (string) $i['qtd'], 'valor-unitario' => (string) $i['preco'], ], $pedido['itens']), ];
$emissao = $api->call('POST', '/nfce/emissao', $body);
if (!in_array($emissao['status'], ['001', '050'])) { throw new \RuntimeException("Emissão falhou: {$emissao['descricao']}"); }
$recibo = $emissao['data']['recibo']; error_log("[emissao] recibo=$recibo request_id={$emissao['meta']['request_id']}");
// Polling $terminais = ['004', '010', '900', '999']; $wait = 5.0; $inicio = microtime(true);
while (microtime(true) - $inicio < 300) { usleep((int) ($wait * 1_000_000)); $consulta = $api->call('GET', "/nfce/cupom/$recibo"); error_log("[polling] status={$consulta['status']}");
if (in_array($consulta['status'], $terminais)) { if ($consulta['status'] === '004') { return $consulta['data']; } throw new \RuntimeException("Status terminal não-sucesso: {$consulta['status']}"); }
$wait = min($wait * 1.5, 30); }
throw new \RuntimeException("Timeout aguardando recibo $recibo");}Retry com backoff
function comRetry(callable $fn, int $max = 3): mixed{ for ($i = 1; $i <= $max; $i++) { try { return $fn(); } catch (ApiError $e) { if (($e->payload['status'] ?? null) === '999') throw $e; if ($i === $max) throw $e; sleep((int) pow(2, $i - 1)); } }}
// Uso$nfce = comRetry(fn() => emitirNFCe($api, $pedido));Helper de polling reutilizável
<?phpconst TERMINAIS = ['004', '010', '900', '999'];
function aguardarRecibo(MyseApi $api, string $pathBase, string $recibo, int $timeoutSec = 300): array { $wait = 5.0; $inicio = microtime(true);
while (microtime(true) - $inicio < $timeoutSec) { usleep((int) ($wait * 1_000_000)); $resp = $api->call('GET', "$pathBase/$recibo"); if (in_array($resp['status'], TERMINAIS)) return $resp; $wait = min($wait * 1.5, 30); } throw new \RuntimeException("Timeout aguardando recibo $recibo");}Emitir NF-e (com transporte completo)
<?phpfunction emitirNFe(MyseApi $api, array $pedido): array { $body = [ 'serie' => '1', 'cfop' => '5102', 'numero-origem' => 'PED-' . $pedido['id'], 'tipo' => 'S', 'finalidade' => 'N', 'valor-despesas' => '0.00', 'cliente' => $pedido['cpf_cnpj_cliente'], 'transporte' => [ 'modalidade' => '0', 'transportadora' => $pedido['transportadora'], 'placa-veiculo' => $pedido['placa'], 'valor-frete' => $pedido['frete'] ?? '0.00', 'valor-seguro' => '0.00', 'peso-bruto' => $pedido['peso_bruto'], 'peso-liquido' => $pedido['peso_liquido'], 'quantidade-volume' => '1', 'especie-volume' => 'Caixa', 'marca-volume' => 'Embalagem', ], 'itens' => array_map(fn($i) => [ 'produto' => $i['sku'], 'quantidade' => (string) $i['qtd'], 'valor-unitario' => (string) $i['preco'], ], $pedido['itens']), 'faturas' => array_map(fn($f) => [ 'valor' => (string) $f['valor'], 'data' => $f['data'], ], $pedido['faturas'] ?? []), ];
$emissao = $api->call('POST', '/nfe/emissao', $body); if (!in_array($emissao['status'], ['001', '050'])) { throw new \RuntimeException("Emissão falhou: {$emissao['descricao']}"); }
$resultado = aguardarRecibo($api, '/nfe/nota', $emissao['data']['recibo']); if ($resultado['status'] !== '004') { throw new \RuntimeException("Status terminal não-sucesso: {$resultado['status']}"); } return $resultado['data']; // inclui sefaz.chave, url-danfe, url-xml}Cancelar NF-e
<?phpfunction cancelarNFe(MyseApi $api, string $chave, string $motivo): array { if (strlen($motivo) < 15 || strlen($motivo) > 255) { throw new \InvalidArgumentException('motivo deve ter entre 15 e 255 caracteres'); } $cancel = $api->call('POST', '/nfe/cancelamento', compact('chave', 'motivo')); if ($cancel['status'] !== '001') throw new \RuntimeException($cancel['descricao']); return aguardarRecibo($api, '/nfe/cancelamento', $cancel['data']['recibo']);}Lançar carta de correção (CC-e)
<?phpfunction cartaCorrecaoNFe(MyseApi $api, string $chave, string $textoCorrecao): array { // CC-e aceita de 15 a 1000 caracteres (desde a 3.15.1); o cancelamento segue em 15 a 255 $tamanho = mb_strlen($textoCorrecao); if ($tamanho < 15 || $tamanho > 1000) { throw new \InvalidArgumentException('texto deve ter entre 15 e 1000 caracteres'); } // O campo "motivo" na CC-e é o TEXTO da correção (xCorrecao). $cce = $api->call('POST', '/nfe/correcao', ['chave' => $chave, 'motivo' => $textoCorrecao]); if ($cce['status'] !== '001') throw new \RuntimeException($cce['descricao']); return aguardarRecibo($api, '/nfe/correcao', $cce['data']['recibo']);}Cancelar NFC-e
<?phpfunction cancelarNFCe(MyseApi $api, string $chave, string $motivo): array { if (strlen($motivo) < 15 || strlen($motivo) > 255) { throw new \InvalidArgumentException('motivo deve ter entre 15 e 255 caracteres'); } $cancel = $api->call('POST', '/nfce/cancelamento', compact('chave', 'motivo')); if ($cancel['status'] !== '001') throw new \RuntimeException($cancel['descricao']); return aguardarRecibo($api, '/nfce/cancelamento', $cancel['data']['recibo']);}Emitir NFS-e (Nota Fiscal de Serviço)
<?phpfunction emitirNFSe(MyseApi $api, array $servico): array { $body = [ 'numero-origem' => 'OS-' . $servico['id'], 'observacao' => $servico['observacao'], 'nome-contato' => $servico['nome_contato'] ?? null, 'telefone-contato' => $servico['telefone_contato'] ?? null, 'data-fim' => $servico['data_fim'], 'cliente' => $servico['cpf_cnpj_cliente'], 'itens' => array_map(fn($i) => [ 'produto' => $i['codigo_servico'], 'quantidade' => (string) $i['qtd'], 'valor-unitario' => (string) $i['preco'], ], $servico['itens']), ];
$emissao = $api->call('POST', '/nfse/emissao', $body); if (!in_array($emissao['status'], ['001', '050'])) { throw new \RuntimeException("Emissão NFSe falhou: {$emissao['descricao']}"); }
$resultado = aguardarRecibo($api, '/nfse/nota', $emissao['data']['recibo']); if ($resultado['status'] !== '004') { throw new \RuntimeException("Status terminal não-sucesso: {$resultado['status']}"); } return $resultado['data'];}Cancelar NFS-e
<?phpfunction cancelarNFSe(MyseApi $api, string $chave, string $motivo): array { if (strlen($motivo) < 15 || strlen($motivo) > 255) { throw new \InvalidArgumentException('motivo deve ter entre 15 e 255 caracteres'); } return $api->call('POST', '/nfse/cancelamento', compact('chave', 'motivo'));}Reconhecer nota de fornecedor (MD-e)
<?php/** * Códigos de reconhecimento: * 210200 — Confirmação da operação (terminal, irreversível) * 210210 — Ciência da operação (provisório, 15 dias) * 210220 — Desconhecimento da operação * 210240 — Operação não realizada */function reconhecerNotaFornecedor(MyseApi $api, string $chave, string $codigo): array { $validos = ['210200', '210210', '210220', '210240']; if (!in_array($codigo, $validos, true)) { throw new \InvalidArgumentException("Código inválido: $codigo"); } $resp = $api->call('POST', '/nffornecedor/reconhecimento', [ 'chave' => $chave, 'codigo-reconhecimento' => $codigo, ]); if ($resp['status'] !== '001') throw new \RuntimeException($resp['descricao']); return aguardarRecibo($api, '/nffornecedor', $resp['data']['recibo']);}Consulta completa por recibo
A consulta simples (/nfe/nota/{recibo}) serve para o polling. A completa devolve todos os dados
do documento. Veja Emitir NF-e e Paginação.
<?php// NF-e: itens, transporte, cliente, faturas, notas referenciadas e dados da SEFAZ// (chave, protocolo, URLs do DANFE e do XML)$nfeCompleta = $api->call('GET', "/nfe/nota/$recibo/completa");
// NFC-e: itens, cliente e dados da SEFAZ$nfceCompleta = $api->call('GET', "/nfce/cupom/$recibo/completa");// Recibo de outra operação (ex.: de um cancelamento) responde status "500".
/** NFC-es pela paginação de path (legado). {pagina} começa em 1; quantidade até 500. */function listarNFCes(MyseApi $api, int $quantidade = 100): \Generator { for ($pagina = 1; ; $pagina++) { $resp = $api->call('GET', "/nfce/paginacao/$pagina/$quantidade"); if ($resp['status'] !== '005' || !is_array($resp['data'] ?? null)) return; foreach ($resp['data'] as $nfce) yield $nfce; if (count($resp['data']) < $quantidade) return; }}Inutilizar numeração
Fecha na SEFAZ uma faixa de NF-e (/nfe/inutilizacao) ou NFC-e (/nfce/inutilizacao) que não foi
usada. Exige certificado A1. Veja Inutilizar numeração.
<?php/** $modelo: 'nfe' (55) ou 'nfce' (65). Para um número só, $final = $inicial. */function inutilizar( MyseApi $api, string $modelo, string $serie, int $inicial, int $final, string $justificativa, ?string $ano = null): array { $tamanho = mb_strlen($justificativa); if ($tamanho < 15 || $tamanho > 255) { throw new \InvalidArgumentException('justificativa deve ter entre 15 e 255 caracteres'); } $body = [ 'serie' => $serie, 'numero-inicial' => (string) $inicial, 'numero-final' => (string) $final, 'justificativa' => $justificativa, ]; if ($ano !== null) { $body['ano'] = $ano; // ano em que a numeração foi GERADA ("26" ou "2026") }
$pedido = $api->call('POST', "/$modelo/inutilizacao", $body); if ($pedido['status'] !== '001') { // 400: faixa com nota autorizada ou em processamento, faixa já na fila, certificado A3... throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); }
$resultado = aguardarRecibo($api, "/$modelo/inutilizacao", $pedido['data']['recibo']); $sefaz = $resultado['data']['sefaz'] ?? []; if ($resultado['status'] !== '004') { // 900 = recusada pela SEFAZ throw new \RuntimeException( 'SEFAZ recusou: ' . ($sefaz['codigo'] ?? '?') . ' ' . ($sefaz['mensagem'] ?? $resultado['descricao']) ); } return $sefaz; // codigo "102" e protocolo}
inutilizar($api, 'nfe', '1', 120, 125, 'Falha no sistema pulou a numeração da série.');XML em lote por período
O ZIP com os XMLs de NF-e ou NFC-e de até 92 dias é gerado em segundo plano: solicite, consulte o protocolo e baixe o link temporário. Veja Baixar XMLs por período.
<?php/** $tipo: 'NFe' ou 'NFCe'. Devolve o caminho do ZIP, ou null se não havia nota. */function baixarXmlPeriodo( MyseApi $api, string $tipo, string $dataInicial, string $dataFinal, string $destino, ?string $email = null): ?string { $body = ['tipo' => $tipo, 'data-inicial' => $dataInicial, 'data-final' => $dataFinal]; if ($email !== null) $body['email'] = $email;
$sol = $api->call('POST', '/xml/solicitacao', $body); // 050 = já havia uma solicitação igual em andamento; o protocolo devolvido é o dela if (!in_array($sol['status'], ['001', '050'], true)) { throw new \RuntimeException($sol['data']['erro'] ?? $sol['descricao']); } $protocolo = $sol['data']['protocolo'];
$wait = 5.0; // intervalo mínimo entre consultas: 2 s $inicio = microtime(true); while (true) { if (microtime(true) - $inicio > 15 * 60) { throw new \RuntimeException("Timeout aguardando protocolo $protocolo"); } usleep((int) ($wait * 1_000_000)); $resp = $api->call('GET', "/xml/solicitacao/$protocolo"); if ($resp['status'] === '005') break; // disponivel if ($resp['status'] === '006') return null; // sem-notas: final, reconsultar não muda if ($resp['status'] !== '002') { // 007 falha (faça NOVA solicitação), 500 inexistente throw new \RuntimeException("Protocolo $protocolo: {$resp['status']} {$resp['descricao']}"); } $wait = min($wait * 1.5, 30); }
// url-download expira em data['expira-em'] (7 dias). Só aceita GET e NÃO leva Authorization: // por isso um cliente Guzzle separado, sem os headers da API. (new \GuzzleHttp\Client())->get($resp['data']['url-download'], [ 'sink' => $destino, 'timeout' => 120, ]); return $destino;}
Resumo diário
Totais por dia de NF-e e NFC-e emitidas, canceladas, denegadas e das falhas, para conciliação. Veja Resumo diário de emissões.
<?php/** Período de até 92 dias, datas AAAA-MM-DD. */function resumoDiario(MyseApi $api, string $dataInicial, string $dataFinal): array { $qs = http_build_query(['data-inicial' => $dataInicial, 'data-final' => $dataFinal]); $resp = $api->call('GET', "/resumo?$qs"); if ($resp['status'] !== '005') throw new \RuntimeException($resp['descricao']); return $resp['data'];}
$resumo = resumoDiario($api, '2026-08-01', '2026-08-06');foreach ($resumo['dias'] as $dia) { // dias sem movimento não aparecem // canceladas é SUBCONJUNTO de emitidas: notas válidas = emitidas - canceladas printf( "%s NF-e válidas=%d NFC-e válidas=%d falhas=%d\n", $dia['data'], $dia['nfe']['emitidas'] - $dia['nfe']['canceladas'], $dia['nfce']['emitidas'] - $dia['nfce']['canceladas'], array_sum($dia['falhas']) );}echo "Falhas no período: {$resumo['totais']['falhas']}\n";Classificação fiscal
Sugestão de NCM, CEST, CFOP, CST, alíquotas, IBS/CBS e ISS de um produto ou serviço, na mesma chamada (sem recibo). Só consulta: não grava nada. Confira a sugestão com o contador antes de emitir. Veja Classificação fiscal.
<?php/** Classifica um item e reenvia com `respostas` enquanto houver pergunta que você sabe responder. */function classificar(MyseApi $api, array $produto, array $respostasConhecidas = []): array { $body = $produto; while (true) { // Sem NCM informado, o motor identifica o item por IA: dê folga ao timeout (70 s) $resp = $api->call('POST', '/classificacao-fiscal', $body, 70); if ($resp['status'] !== '005') { // 400: motivo na descricao, campo em data.campo $campo = $resp['data']['campo'] ?? '?'; throw new \InvalidArgumentException("{$resp['descricao']} (campo=$campo)"); }
$pacote = $resp['data']['pacote']; // chaves do pacote em snake_case $jaRespondidas = $body['respostas'] ?? []; $novas = []; foreach ($pacote['perguntas_pendentes'] ?? [] as $pergunta) { $id = $pergunta['id']; if (array_key_exists($id, $respostasConhecidas) && !array_key_exists($id, $jaRespondidas)) { $novas[$id] = $respostasConhecidas[$id]; } } if (!$novas) { // Sem pendência, ou só sobraram perguntas para mostrar ao usuário ($pergunta['texto']) return $pacote; } $body['respostas'] = $jaRespondidas + $novas; // reenvia o MESMO produto }}
$pacote = classificar($api, [ 'referencia' => 'SKU-NB15', 'nome' => 'NOTEBOOK 15 POLEGADAS 8GB RAM', 'ncm' => '8471.30.12', 'documento' => 'nfe', 'destinatario' => 'contribuinte', 'destino' => 'interestadual',], [ 'empresa_industrial_ou_equiparada_ipi' => false, 'produto_sujeito_st_na_uf' => false,]);echo $pacote['icms']['cfop']['valor'], "\n";
/** Até 10 produtos por chamada. Devolve [resultados, produtos para reenviar]. */function classificarLote(MyseApi $api, array $produtos): array { $resultados = []; $reenviar = []; foreach (array_chunk($produtos, 10) as $fatia) { $resp = $api->call('POST', '/classificacao-fiscal/lote', ['produtos' => $fatia], 90); if ($resp['status'] !== '005') throw new \InvalidArgumentException($resp['descricao']); // Cada item tem status próprio, na ordem do pedido: 005 (pacote), 400 (campo) ou 999 foreach ($resp['data']['resultados'] as $item) { $resultados[] = $item; if ($item['status'] === '999') { // não terminou no prazo do lote: reenvie só ele $reenviar[] = $fatia[$item['indice']]; } } } return [$resultados, $reenviar];}Rotinas
Uma rotina emite NFS-e sozinha em cada data da agenda (recorrente, aluguel, condomínio). Todas as rotas respondem na hora; quem gera recibo é a NFS-e emitida. Veja Rotinas.
<?php// Modelos e os campos (parametros) de cada umforeach ($api->call('GET', '/rotinas/modelos')['data']['modelos'] as $modelo) { echo $modelo['codigo'], ': ', implode(', ', array_column($modelo['parametros'], 'nome')), "\n";}
$rotina = [ 'modelo' => 'NFSE_RECORRENTE', 'nome' => 'Suporte mensal - ACME', 'periodicidade' => 'mensal', 'dia' => 10, 'inicio' => '2026-11-01', // As chaves de parametros são os nomes dos campos do modelo (snake_case). // Os ids vêm de GET /rotinas/clientes?busca= e GET /rotinas/servicos. 'parametros' => [ 'id_clifor' => 1262804, 'id_produto' => 88231, 'vl_servico' => '3.500,50', 'ds_discriminacao' => 'Suporte técnico de {competencia}', ],];
// 1. Conferir sem gravar$conferencia = $api->call('POST', '/rotinas/validar', $rotina);if ($conferencia['status'] !== '005' || !$conferencia['data']['pode-ativar']) { throw new \RuntimeException($conferencia['descricao'] . ' ' . json_encode($conferencia['data'] ?? []));}
// 2. Criar. Sem "ativar", já sai ATIVA e emite nota fiscal sozinha.$criada = $api->call('POST', '/rotinas', $rotina);if ($criada['status'] !== '001') { // 400: data.campo ou data.pendencias throw new \RuntimeException($criada['descricao'] . ' ' . json_encode($criada['data'] ?? []));}$idRotina = $criada['data']['rotina']['id-rotina'];
// 3. A agenda não emite o mês da criação se o dia já passou: emita agora$agora = $api->call('POST', "/rotinas/$idRotina/emitir-agora", ['competencia' => '2026-11']);echo $agora['data']['numero-origem'], "\n"; // ROT-<id>-2026-11: enfileirada, ainda não autorizada
// 4. Histórico: o recibo de cada NFS-e. O desfecho sai em /nfse/nota/{recibo}.foreach ($api->call('GET', "/rotinas/$idRotina/execucoes")['data']['execucoes'] as $execucao) { if (!empty($execucao['recibo'])) { $nfse = aguardarRecibo($api, '/nfse/nota', $execucao['recibo']); echo "{$execucao['competencia']} {$execucao['situacao-descricao']} {$nfse['status']}\n"; }}
// 5. Detalhe: dados, agenda, pendencias, diagnostico (por que emitiu ou não) e execucoes$detalhe = $api->call('GET', "/rotinas/$idRotina");if ($detalhe['status'] === '500') throw new \RuntimeException($detalhe['descricao']); // inexistente ou excluídaecho $detalhe['data']['rotina']['diagnostico'], "\n";
// 6. Alterar: os campos da criação, todos opcionais. Parâmetros parciais (o que não vier fica// como está) e o modelo não muda. Rotina pausada continua pausada, salvo "ativar" => true.$alterada = $api->call('PUT', "/rotinas/$idRotina", ['dia' => 5, 'parametros' => ['vl_servico' => 3800]]);if ($alterada['status'] !== '001') { // 400: data.campo ou data.pendencias throw new \RuntimeException($alterada['descricao'] . ' ' . json_encode($alterada['data'] ?? []));}
// 7. Valor extra em um único mês (só rotina ativa, só nos próximos meses da agenda)$extras = $api->call('GET', "/rotinas/$idRotina/extras")['data'];$competencia = $extras['competencias-disponiveis'][0] ?? null; // AAAA-MMif ($competencia !== null) { $lancado = $api->call('PUT', "/rotinas/$idRotina/extras/$competencia", [ 'valor' => 250, // ou "250,50"; maior que zero 'motivo' => 'Visita técnica extra em 02/12', // 3 a 100 caracteres, vai na descrição da nota ]); if ($lancado['status'] !== '001') throw new \RuntimeException($lancado['descricao']); // 400: ex. condomínio foreach ($lancado['data']['extras'] as $extra) { echo "{$extra['competencia']} {$extra['valor']} {$extra['situacao']}\n"; // Programado... } // Desistiu? Remove o extra (não vale para mês já emitido ou em emissão) $api->call('DELETE', "/rotinas/$idRotina/extras/$competencia");}
// 8. Pausar (só rotina ativa). Retomar: POST /rotinas/{id}/retomar$pausada = $api->call('POST', "/rotinas/$idRotina/pausar");echo $pausada['data']['rotina']['situacao'], "\n"; // "pausada"
// 9. Excluir: status 001 e data.id-rotina$excluida = $api->call('DELETE', "/rotinas/$idRotina");if ($excluida['status'] !== '001') throw new \RuntimeException($excluida['descricao']);Certificado digital A1
Instala o .pfx/.p12 da empresa da chave e acompanha a validade, sem passar pela tela do
FazNota. Desde a 3.20.0. Guarde a senha do arquivo numa variável de ambiente
(MYSE_CERT_SENHA). Veja Certificado digital A1.
<?phpfunction instalarCertificadoA1(MyseApi $api, string $caminhoPfx): array { $arquivo = base64_encode(file_get_contents($caminhoPfx)); // até 50 KB de arquivo $senha = $_ENV['MYSE_CERT_SENHA']; // NUNCA registre em log a senha, o arquivo nem o corpo desta requisição. $resp = $api->call('POST', '/certificado/a1', ['arquivo' => $arquivo, 'senha' => $senha]); if ($resp['status'] !== '001') { // 400: senha errada, não é A1 ICP-Brasil, vencido, de outro CNPJ, vence antes do atual... throw new \RuntimeException($resp['descricao']); } return $resp['data']; // já em uso: a próxima emissão sai assinada com ele}
function conferirCertificado(MyseApi $api): array { $cert = $api->call('GET', '/certificado')['data']; // VALIDO, A_VENCER (até 30 dias), VENCIDO, NAO_INSTALADO ou INDISPONIVEL if (in_array($cert['situacao'], ['A_VENCER', 'VENCIDO', 'NAO_INSTALADO'], true)) { error_log("Certificado {$cert['situacao']}: " . ($cert['dias-para-vencer'] ?? '?') . ' dias para vencer'); } return $cert;}CIOT
Declara na ANTT a operação de transporte de uma ETC e devolve o código do CIOT. Os campos seguem o leiaute PEF da ANTT (PascalCase). Veja Emitir CIOT.
<?phpfunction emitirCiot(MyseApi $api, string $numeroViagem): array { // Não envie CpfCnpjContratado, RNTRCContratado nem IdOperacaoTransporte (vêm do cadastro). $body = [ 'numero-origem' => $numeroViagem, // estável por viagem: reenvio após 999 usa o MESMO valor 'TipoOperacao' => 1, // 1 carga lotação, 2 carga fracionada 'CpfCnpjContratante' => '12345678000199', 'CpfCnpjDestinatario' => '98765432000155', 'ValorFrete' => 1500.00, 'Veiculos' => [['Placa' => 'ABC1D23', 'NumeroEixos' => '4']], 'OrigemDestino' => [[ 'Origem' => ['CodigoMunicipioOrigem' => 4127700], 'Destino' => ['CodigoMunicipioDestino' => 4104808], 'DistanciaPercorrida' => 45, ]], 'DadosCarga' => ['CodigoNaturezaCarga' => 9999, 'CodigoTipoCarga' => 5, 'PesoCarga' => 1000], 'InfIndicadoresOperacionais' => [ 'IndAltoDesempenho' => false, 'IndRetornoVazio' => false, 'ComposicaoVeicular' => false, ], 'InfPagamento' => [[ 'TipoPagamento' => 6, 'IndPagamento' => 0, 'IdentificadorPix' => 'FRETE-2026-1021', ]], ]; $pedido = $api->call('POST', '/ciot/emissao', $body); if ($pedido['status'] !== '001') { // 400: TipoOperacao inválido, A3, sem RNTRC... throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); }
$resultado = aguardarRecibo($api, '/ciot', $pedido['data']['recibo']); if ($resultado['status'] !== '004') { // 900: recusado pela ANTT ou pelo leiaute $data = $resultado['data']; throw new \RuntimeException($data['erro'] ?? $data['antt']['mensagem'] ?? $resultado['descricao']); } return $resultado['data']; // ciot, codigo-verificador, protocolo, situacao}
/** Identifique por "ciot" (o código) ou por "recibo" (o da emissão). */function encerrarCiot(MyseApi $api, string $ciot): array { $pedido = $api->call('POST', '/ciot/encerramento', ['ciot' => $ciot]); if ($pedido['status'] !== '001') { throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); } return aguardarRecibo($api, '/ciot', $pedido['data']['recibo']); // 004 = encerrado}
/** Cancela na ANTT. CIOT que a ANTT recusou (REJEITADO) só é marcado como cancelado no FazNota. */function cancelarCiot(MyseApi $api, string $ciot, string $motivo): array { if ($motivo === '' || mb_strlen($motivo) > 500) { throw new \InvalidArgumentException('motivo é obrigatório, até 500 caracteres'); } $pedido = $api->call('POST', '/ciot/cancelamento', ['ciot' => $ciot, 'motivo' => $motivo]); if ($pedido['status'] !== '001') { throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); } $resultado = aguardarRecibo($api, '/ciot', $pedido['data']['recibo']); if ($resultado['status'] !== '010') { // 010 = cancelado throw new \RuntimeException($resultado['data']['erro'] ?? $resultado['data']['antt']['mensagem'] ?? $resultado['descricao']); } return $resultado['data'];}
/** * Só carga fracionada (TipoOperacao 2): lotação não se retifica, cancele e emita outro. * Informe ao menos um campo; CodigoMunicipioOrigem e CodigoMunicipioDestino vão juntos. */function retificarCiot(MyseApi $api, string $ciot, array $campos): array { $pedido = $api->call('POST', '/ciot/retificacao', ['ciot' => $ciot] + $campos); if ($pedido['status'] !== '001') { throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); } return aguardarRecibo($api, '/ciot', $pedido['data']['recibo']); // 004 = retificado}
$ciot = emitirCiot($api, 'VIAGEM-1021')['ciot'];// Retificação: só se a emissão foi de carga fracionada (TipoOperacao 2)retificarCiot($api, $ciot, ['ValorFrete' => 1650.00, 'PesoCarga' => 1200]);cancelarCiot($api, $ciot, 'Viagem cancelada pelo contratante.');RENAVE
Registra no SERPRO a entrada e a saída de veículos do estoque da revenda, vinculadas à NF-e da operação. Os campos seguem os nomes do SERPRO (camelCase). Veja RENAVE.
<?phpfunction renaveEntradaCompra(MyseApi $api): array { $body = [ 'chaveNFe' => '35261012345678000190550010000012341000012345', // NF-e 55 da própria empresa 'cpfOperadorResponsavel' => '12345678901', 'dataCompra' => '2026-10-20', 'valorCompra' => 45000.00, 'veiculo' => [ 'placa' => 'ABC1D23', 'numeroCrv' => '123456789012', 'renavam' => '01234567890', 'codigoSegurancaCrv' => '12345678901', 'tipoCrv' => 'DIGITAL', 'dataHoraMedicaoHodometro' => '2026-10-20T10:00:00', 'quilometragemHodometro' => 52000, 'documentoProprietarioAtual' => '98765432100', 'tipoDocumentoProprietarioAtual' => 'CPF', ], ]; $pedido = $api->call('POST', '/renave/nota-fiscal/entrada', $body); if ($pedido['status'] !== '001') { // 400: campo obrigatório ausente, sem A1 ou e-mail principal throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); }
// 002 na fila, 003 sendo enviado ao SERPRO: o helper continua consultando $resultado = aguardarRecibo($api, '/renave', $pedido['data']['recibo']); if ($resultado['status'] !== '004') { // 900: recusado pelo SERPRO ou pela validação $data = $resultado['data']; throw new \RuntimeException($data['mensagem'] ?? $data['erro'] ?? $resultado['descricao']); } return $resultado['data']; // guarde 'id-renave': é ele que identifica o cancelamento}
/** * As outras operações seguem o mesmo fluxo: POST, recibo e GET /renave/{recibo}. * 004 registrado (id-renave, id-estoque), 010 cancelado, 900 recusado, 999 reenvie o MESMO pedido. * Os corpos levam CPF, CRV e endereço do comprador: não registre em log o corpo nem a resposta. */function renave(MyseApi $api, string $rota, array $body, string $esperado = '004'): array { $pedido = $api->call('POST', $rota, $body); if ($pedido['status'] !== '001') { throw new \RuntimeException($pedido['data']['erro'] ?? $pedido['descricao']); } $resultado = aguardarRecibo($api, '/renave', $pedido['data']['recibo']); if ($resultado['status'] !== $esperado) { $data = $resultado['data'] ?? []; throw new \RuntimeException($data['mensagem'] ?? $data['erro'] ?? $resultado['descricao']); } return $resultado['data'];}
// Saída do estoque (venda), vinculada à NF-e de venda$saida = renave($api, '/renave/nota-fiscal/saida', [ 'chaveNFe' => '35261012345678000190550010000012401000012400', 'cpfOperadorResponsavel' => '12345678901', 'dataVenda' => '2026-10-25', 'valorVenda' => 52000.00, 'veiculo' => [ 'placa' => 'ABC1D23', 'numeroCrv' => '123456789012', 'renavam' => '01234567890', 'codigoSegurancaCrv' => '12345678901', ], 'comprador' => [ 'nome' => 'Maria Compradora', 'tipoDocumento' => 'CPF', 'numeroDocumento' => '11122233344', 'endereco' => [ 'logradouro' => 'Rua das Flores', 'numero' => '100', 'bairro' => 'Centro', 'cep' => '01001000', 'municipio' => 'São Paulo', 'uf' => 'SP', ], ],]);
// Entrada de veículo que já é da empresa (sem compra). A chaveNFe identifica o movimento no// FazNota e não vai ao SERPRO. Aqui CRV (código e tipo) e hodômetro são obrigatórios.$proprio = renave($api, '/renave/estoque/entrada-veiculo-proprio', [ 'chaveNFe' => '35261012345678000190550010000012411000012411', 'cpfOperadorResponsavel' => '12345678901', 'dataEntradaEstoque' => '2026-10-20', 'veiculo' => [ 'placa' => 'XYZ9A87', 'numeroCrv' => '210987654321', 'renavam' => '09876543210', 'codigoSegurancaCrv' => '10987654321', 'tipoCrv' => 'DIGITAL', 'dataHoraMedicaoHodometro' => '2026-10-20T09:00:00', 'quilometragemHodometro' => 18000, ],]);
// Cancelamentos: por id-renave OU pelo recibo do registro. Os dados do veículo vêm do registro.renave($api, '/renave/estoque/cancelamento-entrada', ['id-renave' => $proprio['id-renave']], '010');renave($api, '/renave/estoque/cancelamento-saida', ['id-renave' => $saida['id-renave']], '010');Listar com paginação
function listarTodosClientes(MyseApi $api): array{ $todos = []; $page = 1; $pageSize = 100;
while (true) { $resp = $api->call('GET', "/clientes?page=$page&page_size=$pageSize"); if ($resp['status'] !== '005' || !is_array($resp['data'] ?? null)) break; $todos = array_merge($todos, $resp['data']); if (count($resp['data']) < $pageSize) break; $page++; usleep(200_000); }
return $todos;}Tratamento de erros
try { $nfce = emitirNFCe($api, $pedido); echo "NFCe emitida: " . ($nfce['sefaz']['chave'] ?? '???') . "\n";} catch (ApiError $e) { error_log(json_encode([ 'event' => 'api_error', 'http_status' => $e->httpStatus, 'request_id' => $e->requestId, 'message' => $e->getMessage(), ])); throw $e;}Variação: cURL puro (sem Guzzle)
function curlCall(string $method, string $path, ?array $body = null): array { $ch = curl_init($_ENV['MYSE_API_BASE'] . $path); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => [ 'Authorization: Token ' . $_ENV['MYSE_API_TOKEN'], 'Content-Type: application/json', ], CURLOPT_TIMEOUT => 30, CURLOPT_POSTFIELDS => $body ? json_encode($body) : null, CURLOPT_HEADER => true, ]); $resp = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_HTTP_CODE); $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE); curl_close($ch);
$headers = substr($resp, 0, $headerSize); $body = substr($resp, $headerSize); return ['status' => $code, 'headers' => $headers, 'body' => json_decode($body, true)];}Health check (sem autenticação)
<?php$res = file_get_contents($_ENV['MYSE_API_BASE'] . '/health');$health = json_decode($res, true);// ["status" => "ok", "database" => "ok", "timestamp" => "..."]/health/deep faz um SELECT 1 no banco e traz as métricas do pool de conexões: 200 saudável,
503 com banco fora ou pool saturado. /health/pool traz só o pool, sem tocar no banco, e sempre
responde 200 (status STARTING enquanto o pool inicializa). Nenhum dos três exige token.
<?php// Cliente sem Authorization e sem exceção em 503: o código HTTP é a resposta do health check$publico = new \GuzzleHttp\Client(['http_errors' => false, 'timeout' => 5]);$base = rtrim($_ENV['MYSE_API_BASE'], '/');
$res = $publico->get("$base/health/deep");$deep = json_decode((string) $res->getBody(), true);if ($res->getStatusCode() === 503) { error_log("API DOWN: " . json_encode($deep)); // {status: "DOWN", check: "deep", ...}} else { // db: ok, latency_ms; pool: active, idle, waiting, total, max, connection_timeout_ms printf("db %d ms, pool %d/%d, aguardando %d\n", $deep['db']['latency_ms'], $deep['pool']['active'], $deep['pool']['max'], $deep['pool']['waiting']);}
$pool = json_decode((string) $publico->get("$base/health/pool")->getBody(), true);echo "{$pool['status']} ativas={$pool['pool']['active']} ociosas={$pool['pool']['idle']}\n";Alterar nota antes da emissão (PUT)
Disponível em NF-e (/nfe/{id}), NFC-e (/nfce/{id}) e NFS-e (/nfse/{id}).
Só funciona enquanto a nota ainda não foi submetida para emissão.
<?phpfunction alterarNota(MyseApi $api, string $tipo, string $id, array $dados): array { // $tipo: 'nfe' | 'nfce' | 'nfse' return $api->call('PUT', "/$tipo/$id", $dados);}
// Uso:alterarNota($api, 'nfe', '12345', [ 'serie' => '1', 'cfop' => '5102', 'cliente' => '12345678000199', 'itens' => [ ['produto' => 'SKU-001', 'quantidade' => '3', 'valor-unitario' => '89.90'], ],]);Listagens
<?php$nfes = $api->call('GET', '/nfe?page=1&page_size=20');$nfces = $api->call('GET', '/nfce?page=1&page_size=50');$nfses = $api->call('GET', '/nfse?dataInicial=2026-05-01&page=1&page_size=20');$fornecedor = $api->call('GET', '/nffornecedor?page=1&page_size=20');
// Forma legada (path-based)$nfesLegado = $api->call('GET', '/nfe/paginacao/1/20');Clientes (CRUD completo)
<?phpfunction cadastrarPF(MyseApi $api, array $dados): array { return $api->call('POST', '/clientes', [ 'tipo' => 'F', 'nome' => $dados['nome'], 'cpf' => $dados['cpf'], 'rg' => $dados['rg'] ?? null, 'consumidor-final' => '1', 'contato' => [ 'email' => $dados['email'] ?? null, 'telefone' => $dados['telefone'] ?? null, ], 'endereco' => $dados['endereco'], ]);}
function cadastrarPJ(MyseApi $api, array $dados): array { return $api->call('POST', '/clientes', [ 'tipo' => 'J', 'razao-social' => $dados['razao_social'], 'nome-fantasia' => $dados['nome_fantasia'] ?? null, 'cnpj' => $dados['cnpj'], 'inscricao-municipal' => $dados['inscricao_municipal'] ?? null, 'tipo-inscricao-estadual' => $dados['contribuinte'] ?? '9', 'inscricao-estadual' => $dados['inscricao_estadual'] ?? 'ISENTO', 'consumidor-final' => $dados['consumidor_final'] ?? '0', 'contato' => [ 'email' => $dados['email'] ?? null, 'telefone' => $dados['telefone'] ?? null, ], 'endereco' => $dados['endereco'], ]);}
// Consultar por CPF/CNPJ$cliente = $api->call('GET', '/clientes/12345678000199');
// Buscar por nome$encontrados = $api->call('GET', '/clientes/busca/exemplo');$top = $api->call('GET', '/clientes/busca/top_clientes');
// Atualizar$api->call('PUT', '/clientes/12345678000199', [ 'tipo' => 'J', 'razao-social' => 'Empresa Exemplo (Novo Nome) Ltda',]);
// Excluir$api->call('DELETE', '/clientes/12345678000199');Produtos (CRUD completo)
<?phpfunction cadastrarProduto(MyseApi $api, array $produto): array { return $api->call('POST', '/produtos', [ 'referencia' => $produto['sku'], 'nome' => $produto['nome'], 'valor' => (string) $produto['valor'], 'medida' => $produto['medida'] ?? 'UN', 'categoria' => $produto['categoria'] ?? null, 'ncm' => $produto['ncm'], 'origem' => $produto['origem'] ?? '0', 'cfop-preferencial' => $produto['cfop'] ?? '5102', 'tipo-produto' => 'P', 'configuracoes-fiscais' => $produto['config_fiscal'] ?? [], ]);}
function cadastrarServico(MyseApi $api, array $servico): array { return $api->call('POST', '/produtos', [ 'referencia' => $servico['sku'], 'nome' => $servico['nome'], 'valor' => (string) $servico['valor'], 'medida' => 'H', 'tipo-produto' => 'S', 'codigo-servico' => $servico['codigo_servico'], ]);}
// Consultar por referência$produto = $api->call('GET', '/produtos/SKU-001');
// Buscar por nome (1º resultado)$porNome = $api->call('GET', '/produtos/nome/Camiseta');
// Listar paginado com busca (use _todos para não filtrar)$todos = $api->call('GET', '/produtos/paginacao/1/20/_todos');$filtrados = $api->call('GET', '/produtos/paginacao/1/20/Camiseta');
// Atualizar$api->call('PUT', '/produtos/SKU-001', [ 'referencia' => 'SKU-001', 'nome' => 'Camiseta Polo M (Novo)', 'valor' => '99.90',]);
// Excluir$api->call('DELETE', '/produtos/SKU-001');