Fiscal Contora | Templates

Templates de documentos

Templates permitem salvar configurações de payload reutilizáveis para criação de documentos fiscais. Ideal para operações recorrentes com mesma configuração tributária, destinatário padrão ou itens frequentes.

GET https://fiscal.contora.com.br/api/v1/templates

POST https://fiscal.contora.com.br/api/v1/templates

Criar template

Ao criar um template, salve o payload base que será reutilizado. O template pode ser vinculado a uma empresa específica ou ficar disponível para todas as empresas do token.

POST https://fiscal.contora.com.br/api/v1/templates

{
  "name": "Venda Padrão Simples Nacional",
  "description": "Template para vendas internas com ICMS 18%, PIS 1.65%, COFINS 7.6%",
  "document_type": "nfe",
  "company_id": "uuid-da-empresa",
  "payload": {
    "nature_operation": "Venda de mercadoria",
    "operation_type": "saida",
    "purpose": 1,
    "consumer_final": true,
    "presence_indicator": 1,
    "items": [
      {
        "ncm": "22030000",
        "cfop": "5102",
        "unit": "UN",
        "taxes": {
          "icms": { "code": "00", "origin": 0, "aliquot": 18 },
          "pis": { "code": "01", "aliquot": 1.65 },
          "cofins": { "code": "01", "aliquot": 7.6 }
        }
      }
    ],
    "payments": [
      { "method": "01" }
    ]
  }
}

{
  "ok": true,
  "data": {
    "id": "uuid-do-template",
    "name": "Venda Padrão Simples Nacional",
    "description": "Template para vendas internas com ICMS 18%, PIS 1.65%, COFINS 7.6%",
    "document_type": "nfe",
    "company_id": "uuid-da-empresa",
    "payload": { ... },
    "is_active": true,
    "created_at": "2026-07-11T10:00:00-03:00",
    "updated_at": "2026-07-11T10:00:00-03:00"
  }
}

Aplicar template

O endpoint apply retorna o payload do template mesclado com os overrides enviados. Isso permite criar documentos rapidamente preenchendo apenas os campos variáveis.

POST https://fiscal.contora.com.br/api/v1/templates/{template_id}/apply

{
  "overrides": {
    "number": 1001,
    "series": 1,
    "recipient": {
      "name": "Cliente Exemplo LTDA",
      "document": "12345678000199",
      "address": {
        "street": "Rua Exemplo",
        "number": "100",
        "district": "Centro",
        "city_name": "Belo Horizonte",
        "city_code": "3106200",
        "state_code": "MG",
        "postal_code": "30140071"
      }
    },
    "items": [
      {
        "code": "SKU-001",
        "name": "Produto Exemplo",
        "quantity": 10,
        "unit_price": 25.50
      }
    ]
  }
}

{
  "ok": true,
  "data": {
    "template_id": "uuid-do-template",
    "document_type": "nfe",
    "payload": {
      "nature_operation": "Venda de mercadoria",
      "operation_type": "saida",
      "purpose": 1,
      "consumer_final": true,
      "presence_indicator": 1,
      "number": 1001,
      "series": 1,
      "recipient": {
        "name": "Cliente Exemplo LTDA",
        "document": "12345678000199",
        "address": { ... }
      },
      "items": [
        {
          "code": "SKU-001",
          "name": "Produto Exemplo",
          "ncm": "22030000",
          "cfop": "5102",
          "unit": "UN",
          "quantity": 10,
          "unit_price": 25.50,
          "taxes": {
            "icms": { "code": "00", "origin": 0, "aliquot": 18 },
            "pis": { "code": "01", "aliquot": 1.65 },
            "cofins": { "code": "01", "aliquot": 7.6 }
          }
        }
      ],
      "payments": [
        { "method": "01" }
      ]
    }
  }
}

Endpoints disponíveis

GET /templates

Listar templates (com filtros)

POST /templates

Criar novo template

GET /templates/{id}

Detalhes do template

PUT /templates/{id}

Atualizar template

DELETE /templates/{id}

Remover template

POST /templates/{id}/apply

Aplicar template com overrides

Filtros de listagem

GET https://fiscal.contora.com.br/api/v1/templates?document_type=nfe&company_id=uuid&is_active=1

document_type

Filtrar por tipo: nfe, nfce, nfse, cte, mdfe

company_id

Filtrar por empresa

is_active

Filtrar por status (1 ou 0)

Fluxo recomendado

Criar templates para os cenários de emissão mais frequentes.
Ao criar documento, usar POST /templates/{id}/apply para obter o payload base.
Enviar o payload retornado para POST /nfe/drafts (ou outro tipo).
Manter templates atualizados quando houver mudança tributária.

Template global Templates sem company_id ficam disponíveis para todas as empresas do token.

Template por empresa Templates com company_id são usados apenas para aquela empresa.

Uso recomendado

Crie templates para cada combinação tributária recorrente.
Use overrides para preencher apenas campos variáveis (número, destinatário, itens).
Mantenha templates inativos quando houver mudança tributária, em vez de deletar.
Templates são ideais para ERPs que emitem documentos com configurações padronizadas.

Reuse configurações fiscais e acelere a criação de documentos.