Integre com uma API REST fácil e segura

Emita NFCom do Modelo 62 com transmissão automática à SEFAZ via SOAP/XML e assinatura com certificado digital A1. Gere um Token de API no painel (Configurações → Tokens) e integre por REST com autenticação via Bearer.

Emissão Modelo 62

Transmissão automática à SEFAZ via SOAP/XML com assinatura digital

Autenticação segura

Bearer Token para API + Certificado A1 obrigatório para transmissão

Assíncrono com Webhooks

Fila em mensageria distribuída com notificações por Webhook; consulte status a qualquer momento

Clientes e Serviços

Emita com criação automática ou gerencie CRUD e vincule na emissão

XML/DANFE por email

Envie manualmente pela API ou automaticamente após autorização

Idempotência e retentativas

Resiliência com chaves idempotentes e retentativas automáticas na fila

Ilustração da API TelcomNFe
API Response
{
  "status": "authorized",
  "data": {
    "invoiceId": "c8f1b2a4-1d2e-43f7-9a8c-0a12b3c4d5e6",
    "workflow": "nfcom-m62",
    "webhookSubscribed": true
  },
  "meta": { "message": "Nota fiscal gerada" }
}
✓ Autenticado

Experiência de desenvolvimento de ponta

Integração completa: emita a nota com todos os dados e o sistema cadastra automaticamente Cliente e Serviços; ou faça o CRUD de ambos e apenas vincule-os na emissão. O processamento é assíncrono via mensageria distribuída com Webhookspara notificação e também há consulta de status. É possível solicitar o envio de XML e DANFE por e-mail manualmente ou automaticamente após a autorização.

  • Autenticação: Bearer Token (gerado no painel)
  • Transmissão SEFAZ: SOAP/XML assinado com Certificado A1
  • Métodos: GET, POST, PUT, PATCH e DELETE
Explore a documentação

Exemplos de API

Use Bearer Token no header Authorization. Certifique-se de ter o Certificado A1 configurado no painel para transmissão automática à SEFAZ.

Pipeline assíncrono baseado em mensageria distribuída
Vantagens: escalabilidade horizontal, retries e backpressure
Entrega ao menos uma vez e reprocessamento idempotente por chave
POST
/api/v2/invoices/nfcom/full
Requisição com dados básicos para emissão de NFCom Modelo 62
Headers
Authorization: Bearer <seu_token>
Content-Type: application/json
curl -X POST "https://api.seudominio.com/api/v2/invoices/nfcom/full"   -H "Authorization: Bearer <seu_token>"   -H "Content-Type: application/json"   -d '{
    "model": 62,
    "issue_date": "2025-02-10T10:00:00.000Z",
    "issue_finality": 0,
    "client": {
      "name": "João Silva",
      "document": "12345678901",
      "indicator_ie": 9,
      "subscriber_type": 1,
      "address": {
        "number": "123",
        "zip_code": "01310100"
      }
    },
    "items": [
      {
        "description": "Internet 100MB",
        "classification_code": "0400401",
        "cfop": "5303",
        "unity": 1,
        "quantity": 1,
        "unit_value": 120.0
      }
    ],
    "billing_info": {
      "billing_type": 0,
      "competence": "202502",
      "due_date": "2025-02-28",
      "usage_period_start": "2025-02-01",
      "usage_period_end": "2025-02-28"
    }
  }'
Ver no OpenAPI
Exemplo de resposta
{
  "success": true,
  "message": "NFCom criada com sucesso",
  "data": {
    "nfcom_id": "c8f1b2a4-1d2e-43f7-9a8c-0a12b3c4d5e6",
    "series": "1",
    "issue_date": "2025-02-10T10:00:00.000Z",
    "status": "SUBMITTED",
    "total_value": 120.0,
    "environment": "homologacao"
  }
}
GET
/api/v2/invoices/status?nfcomId={uuid}
Também suporta number, series, model ou externalReference
Headers
Authorization: Bearer <seu_token>
Content-Type: application/json
curl -X GET "https://api.seudominio.com/api/v2/invoices/status?nfcomId=<uuid>"   -H "Authorization: Bearer <seu_token>"
Ver no OpenAPI
Exemplo de resposta
{
  "nfcom": {
    "id": "c8f1b2a4-1d2e-43f7-9a8c-0a12b3c4d5e6",
    "number": 1234,
    "series": "1",
    "model": 62,
    "status": "SUBMITTED",
    "nfcom_key": "35190500000000000000550010000012345678901234",
    "protocol_number": "135200000000000",
    "environment": "homologacao",
    "issue_date": "2025-02-10T10:00:00.000Z",
    "external_reference": "PED-12345",
    "client": { "name": "João Silva", "document": "12345678901", "email": "joao@exemplo.com" },
    "documents": {
      "xml_url": "https://api.nfcom.telcomnfe.com/api/v2/invoices/c8f1b2a4-1d2e-43f7-9a8c-0a12b3c4d5e6/documents/xml",
      "pdf_url": "https://api.nfcom.telcomnfe.com/api/v2/invoices/c8f1b2a4-1d2e-43f7-9a8c-0a12b3c4d5e6/documents/pdf"
    }
  }
}

Webhooks de notificação

Receba avisos automáticos quando o status da NFCom mudar. Configure uma URL padrão nas Configurações ou informe notification_url no payload.

Notificações por Webhook

Avise seu sistema quando o status da NFCom mudar. Simples e confiável.

Disparo em eventos: submissão e autorização.
Configuração por Configurações → Webhooks ou via notification_url no payload.
Retorne HTTP 2xx para confirmar o recebimento.
Por que fila? Desacopla a emissão, garante retries e escala em picos — com idempotência para evitar duplicidades.
Dica: registre eventos e correlações para auditoria (requestId/external_reference).

Exemplo de Webhook Recebido

Enviado após mudança de status. Cabeçalhos incluem assinatura SHA-256 no header X-TelcomNFe-Signature.

Headers
Content-Type: application/json
Body
{
  "event": "nfcom_authorized",
  "timestamp": "2025-08-29T03:06:00.000Z",
  "message": "NFCom foi autorizada pela SEFAZ",
  "nfcom": {
    "id": "uuid-da-nfcom",
    "number": 123456,
    "series": "1",
    "model": 62,
    "status": "SUBMITTED",
    "nfcom_key": "35250100000000000001620000123456789012345",
    "protocol_number": "135250001234567",
    "environment": "producao",
    "issue_date": "2025-08-29T03:06:00.000Z",
    "client": { "name": "Cliente", "document": "12345678901" }
  }
}
Ver Webhooks na documentação

Perguntas frequentes

Tire suas dúvidas sobre nossa API e como começar a usá-la.

O Modelo 62 substitui as antigas notas 21/22 para comunicação. No TelcomNFe, a transmissão é automática para a SEFAZ via SOAP/XML, com assinatura digital e protocolos de retorno.

Acesse Configurações → Tokens de API no painel, gere um token e utilize-o no header Authorization: Bearer {seu_token}.

Sim. O certificado digital A1 é obrigatório para a transmissão automática à SEFAZ. Sem ele, a emissão ocorre apenas em contingência. Cadastre o arquivo .pfx e a senha nas Configurações.

Assíncrona. As solicitações entram em fila na mensageria distribuída e você é notificado via Webhook. Também é possível consultar o status pela API a qualquer momento.

Sim. Informe a opção de envio no payload de emissão (por exemplo, sendEmail=true e emails=[...]) ou use os endpoints específicos de envio.

Sim. Você pode enviar todos os dados no POST de emissão para criação automática, ou gerenciar via CRUD e apenas vincular os IDs na nota.

Os limites variam conforme o plano. Consulte a documentação ou o suporte para detalhes do seu contrato.

Pronto para integrar com a TelcomNFe?
Plataforma de emissão NFCom (Modelo 62) para telecom.

Emita NFCom (Modelo 62) com API REST, webhooks e automações. Nosso time ajuda você a habilitar o ambiente e ir para produção.