API de integração: clientes, vendas e NF-e

Limites de consulta e uso responsável

A API aceita no máximo 240 requisições por minuto. O limite é compartilhado entre todas as rotas desta API; portanto, listagens, consultas de itens, criação e acompanhamento de movimentos consomem a mesma capacidade.

Para acompanhar NF-e/NFS-e, faça polling moderado — por exemplo, a cada 10 segundos por movimento pendente — e pare assim que houver autorização, rejeição ou retorno para correção.

Dados de referência: empresa, estabelecimento e itens

Estas rotas são somente leitura. Consulte-as antes de criar o movimento para usar os códigos já cadastrados no ERP. Elas não expõem dados fiscais calculados nem permitem alterar os cadastros.

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/empresa?search=matriz

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/estab?empresa=20&per_page=50

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/item?tipo=produto&search=ABC-001

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/item?tipo=servico&search=instalacao

Endpoints publicados

1. Cadastro de pessoa: clientes e fornecedores

Nesta etapa, o sistema remoto cria ou atualiza o cadastro que será usado como cliente ou fornecedor. A pessoa pode ser física ou jurídica, conforme os dados enviados. Informe cidade_ibge; a API localiza internamente o código de cidade do ERP. Para NF-e, mantenha endereço, CEP e número completos.

POST https://ioftalmo.empresarial.inf.br/api/V1/tenant/pessoa
Authorization: Bearer SEU_TOKEN_DE_API
Content-Type: application/json

{
  "nomefantasia": "MERCADO EXEMPLO LTDA",
  "razaosocial": "MERCADO EXEMPLO LTDA",
  "tipopessoa": 1,
  "inscrfederal": "12345678000195",
  "cidade_ibge": "3550308",
  "cliente": 1,
  "email": "financeiro@exemplo.com",
  "logradouro": "RUA",
  "endereco": "DAS FLORES",
  "numero": "100",
  "bairro": "CENTRO",
  "cep": "01001000"
}

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/pessoa?search=12345678000195&cliente=1&per_page=50

PATCH https://ioftalmo.empresarial.inf.br/api/V1/tenant/pessoa/456
Content-Type: application/json

{ "fone1": "11999999999", "email": "novo-contato@exemplo.com", "cliente": 1 }

DELETE https://ioftalmo.empresarial.inf.br/api/V1/tenant/pessoa/456

A exclusão só é realizada quando não houver vínculos com outros registros. Caso a pessoa já tenha sido usada, a API responde 422; mantenha o cadastro e, se necessário, marque-o como inativo. O campo cidade interno não é aceito pela integração: envie sempre o código IBGE em cidade_ibge. Para emitir NF-e, complete antes o endereço fiscal do destinatário, incluindo CEP válido e número.

2. Cadastro de movimento de venda

Nesta etapa, o sistema remoto registra a venda, compra ou serviço, vinculando a pessoa cadastrada e os itens comercializados. O ERP aplica automaticamente as configurações padrão do estabelecimento — tipo de movimento, série, carteira, condição de pagamento e demais regras.

A integração não precisa administrar tipo, carteira, condição de pagamento, operação de movimento ou série. Em cada criação, a API ignora qualquer tipomov recebido e usa o tipo padrão do estabelecimento, exatamente como a inclusão pelo Docmov interno. Os itens usam a operação vinculada a esse tipo, salvo opmov explicitamente informado no item.

POST https://ioftalmo.empresarial.inf.br/api/V1/tenant/docmov
Authorization: Bearer SEU_TOKEN_DE_API
Content-Type: application/json

{
  "empresa": 1,
  "estab": 1,
  "pessoa": 456,
  "dataemissao": "2026-07-16",
  "obs": "PEDIDO ORIGEM LOJA VIRTUAL #10001",
  "produtos": [
    { "item": 789, "qtid": 2, "valor": 49.90, "desconto": 0 }
  ]
}

O exemplo omite docserie, carteira e condicao_pagamento para usar os padrões. Se o tipo padrão ou algum de seus vínculos não estiver configurado, a criação retorna 422; ajuste a configuração do estabelecimento/tipo de movimento no ERP antes de reenviar.

Dados adicionais: frete e indicador de presença

São opcionais; quando omitidos, usam o padrão do tipo de movimento.

{ "frete": 1, "indpres": 2 }

3. Situação do movimento e transmissão de NF-e

Não há uma chamada fiscal separada. Envie situacao: 1 para salvar o movimento pendente (é o padrão), ou situacao: 2 para salvá-lo já concluído. A transição para 2 efetiva o movimento e, quando a série resolvida for uma série de NF-e e a configuração fiscal estiver ativa, valida e agenda a transmissão automaticamente.

POST https://ioftalmo.empresarial.inf.br/api/V1/tenant/docmov
Authorization: Bearer SEU_TOKEN_DE_API
Content-Type: application/json

{
  "empresa": 1,
  "estab": 1,
  "pessoa": 456,
  "situacao": 2,
  "produtos": [{ "item": 789, "qtid": 1, "valor": 49.90 }]
}

PATCH https://ioftalmo.empresarial.inf.br/api/V1/tenant/docmov/9001
Content-Type: application/json

{ "situacao": 2, "atualizar_data_emissao": false }

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/docmov/9001

• 1 — Pendente: permite completar ou alterar o movimento depois.
• 2 — Concluído: efetiva o movimento e inicia o fluxo fiscal quando aplicável.
• atualizar_data_emissao: true substitui data e hora de emissão pelo momento da conclusão.
• Uma falha de validação fiscal impede a transição para 2 e retorna 422 com erros.
• Uma resposta 200 confirma a conclusão e o agendamento; a autorização fiscal é assíncrona.
• Não considere a NF-e autorizada apenas por situacao: 2. Consulte nfe_status, nfe_situacao e nfe_autorizada; quando autorizada, a resposta também terá nfe_chave e nfe_protocolo.
• Em caso de rejeição ou falha no processamento assíncrono, o sistema pode reabrir o movimento para situacao: 1. Corrija os dados, consulte nfe_status e nfe_status_retorno, e envie novamente situacao: 2.
• Uma NF-e já emitida ou em processamento não é reenviada automaticamente.

Para NFS-e, acompanhe também os campos específicos devolvidos pelo movimento, como nfse_enviado e nfse_rps. A integração deve guardar o código do movimento e realizar polling por GET /docmov/{codigo} até haver autorização, rejeição ou necessidade de correção.

Status fiscal retornado no movimento

Toda consulta de Movimento retorna nfe_status (código), nfe_status_descricao, nfe_situacao, nfe_autorizada, nfe_cancelada e nfe_emitida. Use os campos booleanos para a decisão da integração e conserve o código para auditoria.

{
  "situacao": 2,
  "nfe_status": 100,
  "nfe_status_descricao": "NF-e autorizada pela SEFAZ",
  "nfe_situacao": "autorizada",
  "nfe_autorizada": true,
  "nfe_cancelada": false,
  "nfe_emitida": true,
  "nfe_chave": "...",
  "nfe_protocolo": "..."
}

Filtros, paginação e respostas

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/docmov?empresa=1&estab=1&dataemissao_ini=2026-07-01&dataemissao_fim=2026-07-31&per_page=50

{
  "sucesso": true,
  "mensagem": "obtidos com sucesso",
  "data": [],
  "meta": { "pagina_atual": 1, "ultima_pagina": 1, "por_pagina": 50, "total": 0 }
}

• 200: consulta, alteração, conclusão ou cancelamento executado.
• 201: registro criado; use o campo codigo retornado nas próximas chamadas.
• 401: token ausente, inválido ou sem acesso ao tenant.
• 404: recurso não encontrado.
• 422: payload inválido, vínculo inexistente, bloqueio ou regra fiscal não atendida.

Dados retornados e XML fiscal

As respostas de Movimento expõem somente dados operacionais: identificadores, datas, situação, totais comerciais, itens, parcelas e retorno fiscal. Bases, alíquotas, valores calculados de impostos, regras internas e XML não são incluídos no JSON do movimento.

GET https://ioftalmo.empresarial.inf.br/api/V1/tenant/docmov/9001/xml
Authorization: Bearer SEU_TOKEN_DE_API
Accept: application/xml

• O detalhe do movimento informa xml_disponivel e xml_url.
• Quando disponível, a rota responde o XML puro com Content-Type: application/xml.
• Enquanto não houver XML autorizado/disponível, a rota retorna 404.
• Use o XML como fonte fiscal completa; não tente recalcular impostos a partir do JSON operacional.