Pular para o conteúdo

Exemplos em PHP

Setup

Terminal window
composer require guzzlehttp/guzzle vlucas/phpdotenv
.env
MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/rest
MYSE_API_TOKEN=seu_token_aqui

Cliente HTTP centralizado

src/MyseApi.php
<?php
namespace 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

<?php
function 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

<?php
const 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)

<?php
function 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

<?php
function 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)

<?php
function 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

<?php
function 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)

<?php
function 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

<?php
function 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;
}
baixarXmlPeriodo($api, 'NFe', '2026-04-01', '2026-04-30', 'nfe-2026-04.zip', '[email protected]');

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 um
foreach ($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ída
echo $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-MM
if ($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.

<?php
function 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.

<?php
function 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,
'ChavePix' => '[email protected]',
'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.

<?php
function renaveEntradaCompra(MyseApi $api): array {
$body = [
'chaveNFe' => '35261012345678000190550010000012341000012345', // NF-e 55 da própria empresa
'cpfOperadorResponsavel' => '12345678901',
'dataCompra' => '2026-10-20',
'valorCompra' => 45000.00,
'emailVendedor' => '[email protected]',
'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',
'email' => '[email protected]',
'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.

<?php
function 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)

<?php
function 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)

<?php
function 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');