POST/nfse

Issue a service invoice

The API validates the JSON schema and business rules. If everything is valid, you receive an ID for each invoice and the document is forwarded to City Hall. This route is asynchronous. Check status at GET /nfse/consultar/{idNotaOrProtocol}, or register a webhook on the organization or company to be notified when processing finishes. Foreign customer: - For municipalities served by the DSF provider, send the foreign document in the tomador.cpfCnpj field. Notes: - Generate a unique idIntegracao per invoice. Duplicate requests with the same identifier are processed only once. - Processing time depends on the City Hall webservice. - Providers that have never issued via webservice usually need City Hall homologation. - Maximum batch size is 500 invoices.

Production: https://api.otentecnologia.com.brSandbox: https://api.sandbox.otentecnologia.com.br

Parameters

This route has no path or query parameters.

Request

cURL

curl -X POST 'https://api.otentecnologia.com.br/nfse' \
  -H 'x-api-key: $OTEN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "idIntegracao": "SP-2026-0001",
    "prestador": {
      "cpfCnpj": "00000000000000"
    },
    "tomador": {
      "cpfCnpj": "11111111000191",
      "razaoSocial": "Cliente Exemplo LTDA",
      "inscricaoMunicipal": "12345678",
      "email": "financeiro@cliente.com",
      "endereco": {
        "tipoLogradouro": "Avenida",
        "logradouro": "Paulista",
        "numero": "1000",
        "complemento": "Conjunto 101",
        "bairro": "Bela Vista",
        "tipoBairro": "Bairro",
        "codigoCidade": "3550308",
        "descricaoCidade": "Sao Paulo",
        "estado": "SP",
        "cep": "01310100"
      }
    },
    "cidadePrestacao": {
      "codigo": "3550308",
      "descricao": "Sao Paulo"
    },
    "servico": [
      {
        "codigo": "1.05",
        "codigoTributacao": "1.05",
        "discriminacao": "Licenca de uso de software e suporte tecnico mensal.",
        "cnae": "6203100",
        "codigoCidadeIncidencia": "3550308",
        "descricaoCidadeIncidencia": "SAO PAULO",
        "iss": {
          "tipoTributacao": 6,
          "exigibilidade": 1,
          "retido": false,
          "aliquota": 2.9
        },
        "valor": {
          "servico": 1500,
          "descontoCondicionado": 0,
          "descontoIncondicionado": 0
        }
      }
    ]
  }
]'

Body

application/json

[
  {
    "idIntegracao": "SP-2026-0001",
    "prestador": {
      "cpfCnpj": "00000000000000"
    },
    "tomador": {
      "cpfCnpj": "11111111000191",
      "razaoSocial": "Cliente Exemplo LTDA",
      "inscricaoMunicipal": "12345678",
      "email": "financeiro@cliente.com",
      "endereco": {
        "tipoLogradouro": "Avenida",
        "logradouro": "Paulista",
        "numero": "1000",
        "complemento": "Conjunto 101",
        "bairro": "Bela Vista",
        "tipoBairro": "Bairro",
        "codigoCidade": "3550308",
        "descricaoCidade": "Sao Paulo",
        "estado": "SP",
        "cep": "01310100"
      }
    },
    "cidadePrestacao": {
      "codigo": "3550308",
      "descricao": "Sao Paulo"
    },
    "servico": [
      {
        "codigo": "1.05",
        "codigoTributacao": "1.05",
        "discriminacao": "Licenca de uso de software e suporte tecnico mensal.",
        "cnae": "6203100",
        "codigoCidadeIncidencia": "3550308",
        "descricaoCidadeIncidencia": "SAO PAULO",
        "iss": {
          "tipoTributacao": 6,
          "exigibilidade": 1,
          "retido": false,
          "aliquota": 2.9
        },
        "valor": {
          "servico": 1500,
          "descontoCondicionado": 0,
          "descontoIncondicionado": 0
        }
      }
    ]
  }
]

Responses

200OK

JSON

{
  "documents": [
    {
      "idIntegracao": "XXXYY999",
      "prestador": "08187168000160",
      "id": "5eb6caf7cbb4e8dce016c39f"
    }
  ],
  "message": "Nota(as) em processamento",
  "protocol": "7c09beca-1b2a-4acb-bd63-2f37a0e2ee1a"
}

400Bad Request

JSON

{
  "error": {
    "message": "Não foi possível enviar 501 documentos, pois o limite máximo de 500 NFS-e em um único JSON foi atingido."
  }
}

401Unauthorized

JSON

{
  "error": {
    "message": "O token informado é inválido. Para o ambiente de produção, Acesse https://www.otentecnologia.com.br/, e gere o seu TOKEN de acesso"
  }
}

409Conflict

JSON

{
  "error": {
    "message": "Já existe um(a) NFSe com os parâmetros informados",
    "data": {
      "new": {
        "idIntegracao": "TESTE",
        "cnpj": "8187168000160"
      },
      "current": {
        "id": "5exxxe508efc9a95e999faa0",
        "idIntegracao": "TESTE",
        "emissao": "13/04/2020",
        "tipoAutorizacao": "WEBSERVICE",
        "situacao": "CONCLUIDO",
        "prestador": "8187168000160",
        "tomador": "8187168000160",
        "valorServico": 20,
        "numeroNfse": "999",
        "serie": "1",
        "lote": 0,
        "numero": 1,
        "codigoVerificacao": "XXXX",
        "autorizacao": "30/08/2011",
        "mensagem": "RPS Autorizada com sucesso",
        "pdf": "https://api.otentecnologia.com.br/nfse/pdf/5exxxe508efc9a95e999faa0",
        "xml": "https://api.otentecnologia.com.br/nfse/xml/5exxxe508efc9a95e999faa0"
      }
    }
  }
}