A API de Emissão de Nota Fiscal de Serviços da Celcoin (NFs-e) permite que as aplicações integradas possam fazer toda a gestão de Notas Fiscais da sua empresa e empresas conectadas ao seu ecossistema. Com ela é possível gerir as empresas e Notas Fiscais emitidas. Neste serviço o cliente consegue emitir notas Fiscais inicialmente para 8 Prefeituras.

Caso de uso:

Como Fintech quero conseguir disponibilizar as empresas do meu ecossistema a possibilidade de realizar emissões de NFs-e para os serviços prestados.

Nesse artigo você irá aprender sobre:

Limitações e exceções
Cidades Suportadas
Configurar um webhook para receber as informações das NFs-e emitidas.
Gestão de Empresas
Gestão do Certificado Digital
Gestão de uma NFs-e
Homologação

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link
Ter familiaridade com apis Rest usando o protocolo OAuth 2.0.
Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail corp@celcoin.com.br. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Limitações e exceções:

Esse produto emite apenas notas fiscais de serviço

É obrigatório o uso de certificado A1 Para as Emissões de NFs-e

Cidades Suportadas:

É possível emitir NFs-e na seguintes cidades:

São Paulo
Campinas
São José dos Campos
Rio de Janeiro
Niterói
Porto Alegre
Florianópolis
Balneário Camboriú

⚠️
Atenção!
Mesmo em ambiente de sandbox é necessário utilizar o certificado A1 da empresa que irá emitir as NFs-e.

Configurando webhook

Para conseguir receber da Celcoin as notas fiscais emitidas de seus usuários é necessário realizar a configuração de um webhook.

O webhook é uma forma de receber informações de forma assíncrona, geralmente são disparados gatilhos no formato JSON quando um evento acontece, na prática para as apis de Emissão de NFS-e será usado para receber informações em seu sistema sobre as NFs-e emitidas, onde é possível receber os eventos de sucesso, com os dados da nota fiscal ou cancelamento da mesma. Inclusive quando ocorre alguma falha na emissão.

A Celcoin possui um gerenciador de webhook, para configurar o produto de Emissão de Nota Fiscal, basta seguir os passos do artigo Cadastrar e Gerenciar Webhooks

Abaixo será exibido o modelo de retorno do webhook

Modelos de Retorno Webhooks

Registro da NFs-e (invoice-nfse-registration) e Cancelamento da NFs-e (invoice-nfse-cancellation)


{
  "serviceInvoiceId": "6761cf89b9fcb2eb27f9d6af",
  "requestId": "d2e5b7c1-9a3f-4a6e-8f7b-1c9d3b2f6a4e",
  "rpsSerial": 1,
  "rpsNumber": 1,
  "operationType": "TRIBUTACAO_MUNICIPIO",
  "client": {
    "documentType": "CNPJ",
    "document": "51236721000136",
    "name": "Razão Social",
    "cityRegistration": "12345678912345",
    "stateRegistration": "12345678912345",
    "email": "email@google.com",
    "phone": "11912345678",
    "address": {
      "street": "Logradouro",
      "number": "1",
      "neighborhood": "Bairro",
      "cityCode": "3550308",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "complement": "Casa",
      "zipCode": "08190120"
    }
  },
  "service": {
    "cnae": "62091",
    "code": "1.07",
    "cityTaxCode": "3158",
    "cityTaxDescription": "SUPORTE TÉCNICO, MANUTENÇÃO E OUTROS SERVIÇOS EM TECNOLOGIA DA INFORMAÇÃO",
    "description": "Prestação de Serviço",
    "value": 1000,
    "deductionValue": 0,
    "unconditionalDiscount": 0,
    "conditionalDiscount": 0,
    "retentionValue": 0,
    "pisValue": 0,
    "cofinsValue": 0,
    "inssValue": 0,
    "irValue": 0,
    "csllValue": 0,
    "issRetained": true,
    "issRate": 1,
    "baseValue": 1010,
    "issRetainedValue": 10,
    "netValue": 1000,
    "address": {
      "street": "Logradouro",
      "number": "1",
      "neighborhood": "Bairro",
      "cityCode": "3550308",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Casa",
      "zipCode": "08190120"
    }
  },
  "status": "APPROVED",
  "competenceDate": "2025-02-05T19:57:03.985Z",
  "created": "2025-02-05T19:57:03.985Z"
}

📘
Note que o que vai mudar nos cenários de retorno dos webhooks da solicitação de Emissão de uma NFs-e e a Solicitação de Cancelamento de uma NFs-e é o status , que pode assumir o valor de Aprovado "APPROVED" ou cancelado "CANCELED" respectivamente.

Nota Fiscal - Cenário de Erro

📘
Caso ao solicitar a emissão de NFs-e e ela for rejeitada na prefeitura, o retorno do webhook virá com o status de "REJECTED"

Gestão de Empresas

A funcionalidade de gestão de empresas tem o objetivo de cadastrar e consultar dados das empresas que irão emitir notas fiscais em seu ecossistema. A seguir iremos demonstrar como realizar os cadastros e consultas nas APIs que compõe esse fluxo.

Cadastrar uma empresa para Emissão de NFs-e

Para cadastrar uma empresa é necessário realizar uma chamada na api Cadastrar Empresa utilizando o método POST, onde precisa ser preenchido algumas informações relacionadas a empresa que realizará a emissão da Nota Fiscal de Serviço. Os dados necessários estão no quadro "Parâmetros do Body"

Modelo de requisição:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/company' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "document": "51236721000136",
  "name": "Razão Social",
  "fantasyName": "Nome Fantasia",
  "cityRegistration": "12345678912345",
  "stateRegistration": "12345678912345",
  "stateTaxSubstituteRegistration": "1234567891",
  "cnae": "62091",
  "optSimpleNational": true,
  "email": "email@google.com",
  "phone": "11912345678",
  "address": {
    "street": "Logradouro",
    "number": "1",
    "neighborhood": "Bairro",
    "cityCode": "3550308",
    "city": "São Paulo",
    "state": "SP",
    "complement": "Casa",
    "zipCode": "08190120"
  },
  "serviceInvoice": {
 	  "rpsSerial": "1",
    "rpsNumber": 1,
    "code": "1.07",
    "cityTaxCode": "3158",
    "cityTaxDescription": "SUPORTE TÉCNICO, MANUTENÇÃO E OUTROS SERVIÇOS EM TECNOLOGIA DA INFORMAÇÃO",
    "specialTaxType": "MICROEMPRESA_MUNICIPAL",
    "issRate": 1,
    "culturalSupporter": true
  }
}
'

Parâmetros do Body:

Campo	Descrição	Tipo
document	CNPJ da Empresa	String (14)
name	Razão Social da Empresa	String (60)
fantasyName	Nome Fantasia da Empresa	String (60)
cityRegistration	Inscrição Municipal	String (14)
stateRegistration	Inscrição Estadual	String (14)
stateTaxSubstituteRegistration	Inscrição Estadual de Substituto Tributário	String (10)
cnae	CNAE - Classificação Nacional de Atividades Econômicas	String (10)
optSimpleNational	Optante pelo Simples Nacional	Boolean
email	e-mail	String (60)
phone	Telefone	String (11)
address.street	Logradouro	String (60)
address.number	Número	String (10)
address.neighborhood	Bairro	String (60)
address.cityCode	Código de Município	String (7)
address.city	Município	String (60)
address.state	Sigla de Estado	String (2)
address.complement	Complemento	String
address.zipCode	CEP	String (8)
serviceInvoice.code	Código de Serviço Prestado	String (15)
serviceInvoice.rpsSerial	Série RPS de Documento Fiscal.	String (5)
serviceInvoice.rpsNumber	Número RPS de Documento Fiscal.	Int 64
serviceInvoice.cityTaxCode	Código de Tributação de Município	String (20)
serviceInvoice.cityTaxDescription	Descrição de Tributação de Município	String (255)
serviceInvoice.specialTaxType	Regime Especial Tributário	String
serviceInvoice.issRate	Aliquota de ISS	Number(double)
serviceInvoice.culturalSupporter	Incentivador Cultural.	Boolean

Modelo de retorno:


{
  "document": "51236721000136",
  "name": "Razão Social",
  "fantasyName": "Nome Fantasia",
  "cityRegistration": "12345678912345",
  "stateRegistration": "12345678912345",
  "stateTaxSubstituteRegistration": "1234567891",
  "cnae": "62091",
  "optSimpleNational": true,
  "email": "email@google.com",
  "phone": "11912345678",
  "address": {
    "street": "Logradouro",
    "number": "1",
    "neighborhood": "Bairro",
    "cityCode": "3550308",
    "city": "São Paulo",
    "state": "SP",
    "complement": "Casa",
    "zipCode": "08190120"
  },
  "serviceInvoice": {
    "rpsSerial": "1",
    "rpsNumber": 1,
    "code": "1.07",
    "cityTaxCode": "3158",
    "cityTaxDescription": "SUPORTE TÉCNICO, MANUTENÇÃO E OUTROS SERVIÇOS EM TECNOLOGIA DA INFORMAÇÃO",
    "specialTaxType": "MICROEMPRESA_MUNICIPAL",
    "issRate": 1,
    "culturalSupporter": true
  },
  "created": "2025-02-05T19:49:58.175Z",
  "updated": "2025-02-05T19:49:58.175Z",
  "companyId": "663167f4fa5fb59547f01ca3"
}

Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro da empresa.

Tabela descritiva dos campos retornados

📘
Além dos campos informados na criação, o retorno da requisição enviamos alguns dados adicionais. Segue descrição abaixo

Campo	Descrição	Tipo
created	Data de Criação.	String ($date-time)
updated	Data de Atualização.	String ($date-time)
companyId	Identificador da Empresa	String

Consultar Empresa Cadastrada

Para consultar uma empresa cadastrada é necessário realizar uma chamada na api Consultar Empresa Cadastrada utilizando o método GET, onde precisa ser enviado na requisição o Id da empresa cadastrada.

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/company/663167f4fa5fb59547f01ca3' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{acess_token}}' \
--header 'Content-Type: application/json' \

Modelo de retorno:

{
  "document": "51236721000136",
  "name": "Razão Social",
  "fantasyName": "Nome Fantasia",
  "cityRegistration": "12345678912345",
  "stateRegistration": "12345678912345",
  "stateTaxSubstituteRegistration": "1234567891",
  "cnae": "62091",
  "optSimpleNational": true,
  "email": "email@google.com",
  "phone": "11912345678",
  "address": {
    "street": "Logradouro",
    "number": "1",
    "neighborhood": "Bairro",
    "cityCode": "3550308",
    "city": "São Paulo",
    "state": "SP",
    "complement": "Casa",
    "zipCode": "08190120"
  },
  "certificate": {
    "key": "company-51236721000136",
    "password": "123456789"
  },
  "serviceInvoice": {
    "code": "1.07",
    "cityTaxCode": "3158",
    "cityTaxDescription": "SUPORTE TÉCNICO, MANUTENÇÃO E OUTROS SERVIÇOS EM TECNOLOGIA DA INFORMAÇÃO",
    "specialTaxType": "MICROEMPRESA_MUNICIPAL",
    "issRate": 1,
    "culturalSupporter": true
  },
  "created": "2025-02-05T19:53:49.013Z",
  "updated": "2025-02-05T19:53:49.013Z",
  "companyId": "663167f4fa5fb59547f01ca3"
}

📘
Note que é enviado as informações da empresa cadastrada, inclusive caso já tenha efetuado o cadastro do certificado Digital, ele é informado na consulta de Empresas.

📘
Essa chamada também é síncrona, e na sequência já enviamos as informações sobre a empresa consultada.

Gestão de Certificado

Essa funcionalidade permite realizar o cadastro do certificado digital, item obrigatório para realizar as emissões de Notas Fiscais de Serviço. A seguir iremos explicar o que é e como realizar o cadastro do certificado digital.

Cadastrar um certificado Digital

Após o cadastro da empresa, é necessário realizar o cadastro do certificado digital. Para isso será necessário realizar uma chamada na api Cadastrar Certificado Digital utilizando o método POST, onde na requisição você deve informar o Id da empresa que utilizará o certificado e no corpo da requisição é necessário realizar o upload do arquivo PFX e a senha do mesmo. Com isso a empresa estará apta a realizar a emissão da Nota Fiscal de Serviço. Mais detalhes dos dados necessários estão no quadro "Parâmetros do Body"

Modelo de requisição:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/company/{id}/certificate' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'File=' \
  -F 'Password=123456789'

Parâmetros do Body:

Campo	Descrição	Tipo
File	Arquivo PFX do Certificado	string($binary)
Password	Senha do Arquivo PFX	String

Modelo de retorno:

Após as validações internas a API retornará a requisição como sucesso, informando o código 200.

📘
Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro do certificado digital.

📘
Os dados do seu certificado estão ficarão em um ambiente seguro e só será utilizado no momento das emissões das suas NFs-e.

Gestão de Notas

Uma vez que a empresa já está cadastrada e os certificados vinculados, já é possível emitir uma nota fiscal de Serviço. Para emissão da NFs-e, será disponibilizado APIs para tal. Essas APIs terão as seguintes funcionalidades: Emissão NFs-e e Cancelamento NFs-e. Abaixo será demonstrado o que é cada funcionalidade e como utilizar.

Emissão da NFs-e

Para realizar a emissão de NFS-e será necessário realizar uma chamada na api Emitir Nota Fiscal de Serviço utilizando o método POST, onde precisa ser preenchido algumas informações relacionadas a NFs-e que será emitida. Todas as informações necessárias para emissão de NFs-e estão no quadro "Parâmetros do Body"

Modelo de requisição:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/nfse' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "companyId": "6514d4db5f9a3c2e8b1d7f5a",
  "operationType": "TRIBUTACAO_MUNICIPIO",
  "client": {
    "documentType": "CNPJ",
    "document": "51236721000136",
    "name": "Lucas",
    "cityRegistration": "111111111111",
    "stateRegistration": "2222222222",
    "email": "lucas@example.com",
    "phone": "119999999999",
    "address": {
      "street": "Rua Sem",
      "number": "123",
      "neighborhood": "Jardim Sem",
      "cityCode": "1200013",
      "city": "Acrelandia",
      "state": "AC",
      "country": "BR",
      "complement": "Perto do parque",
      "zipCode": "000000000"
    }
  },
  "service": {
    "cnae": "1111111111",
    "code": "8.01",
    "cityTaxCode": "IPTU",
    "cityTaxDescription": "Tarifado",
    "description": "Manutenção de computadores",
    "values": {
      "value": 1000,
      "deductionValue": 0,
      "unconditionalDiscount": 0,
      "conditionalDiscount": 0,
      "retentionValue": 0,
      "pisValue": 0,
      "cofinsValue": 0,
      "inssValue": 0,
      "irValue": 0,
      "csllValue": 0,
      "issRetained": 0,
      "issRate": 0
    },
    "address": {
      "street": "Rua Sem",
      "number": "123",
      "neighborhood": "Jardim Sem",
      "cityCode": "1200013",
      "city": "Acrelandia",
      "state": "AC",
      "complement": "Perto do parque",
      "zipCode": "000000000"
    }
  },
  "competenceDate": "2024-12-25",
  "requestId": "9b37e3f9-c59e-4b47-a93e-41f66e89df88"
}
'

Parâmetros do Body:

Campo	Descrição	Tipo
companyId	Identificador único da empresa.	String
operationType	Tipo de Operação. Valores possíveis para informar no campo: 1. TRIBUTACAO_MUNICIPIO - Tributação no Município. 2. TRIBUTACAO_FORA_MUNICIPIO - Tributação fora do Município. 3. ISENTO - Isenção. 4. IMUNE - Imune. 5. EXIGIBILIDADE_SUSPENSA_DECISAO_JUDICIAL - Exigibilidade Suspensa por Decisão Judicial. 6. EXIGIBILIDADE_SUSPENSA_PROC_ADM - Exigibilidade Suspensa por Procedimento Administrativo.	String (10)
client.documentType	Tipo do Documento do cliente que a NFs-e será emitida	String (20)
client.document	CNPJ ou CPF do cliente que a NFs-e será emitida	String (20)
client.name	Razão Social ou Nome do cliente que a NFs-será emitida	String (115)
client.cityRegistration	Inscrição Municipal.	String
client.stateRegistration	Inscrição Estadual.	String
client.email	E-mail	String (60)
client.phone	Telefone	String
client.address.street	Logradouro	String (60)
client.address.number	Número	String (10)
client.address.neighborhood	Bairro	String (60)
client.address.cityCode	Código de Município.	String
client.address.city	Município	String
client.address.state	Sigla de Estado	String (2)
client.address.country	Sigla de País	String (2)
client.address.complement	Complemento do endereço	String
client.address.zipCode	CEP	String
service.cnae	CNAE - Classificação Nacional de Atividades Econômicas	String (10)
service.code	Código do serviço prestado	String (15)
service.cityTaxCode	Código de Tributação de Município.	String
service.cityTaxDescription	Descrição de Tributação de Município.	String (255)
service.description	Discriminação do Serviço	String (7000)
service.values.value	Valor	Number (double)
service.values.deductionValue	Valor de dedução	Number (double)
service.values.unconditionalDiscount	Valor de desconto incondicionado.	Number (double)
service.values.conditionalDiscount	Valor de desconto condicionado.	Number (double)
service.values.retentionValue	Valor de outras Retenções.	Number (double)
service.values.pisValue	Valor de PIS.	Number (double)
service.values.cofinsValue	Valor de COFINS.	Number (double)
service.values.inssValue	Valor de INSS.	Number (double)
service.values.irValue	Valor de IR.	Number (double)
service.values.csllValue	Valor de CSLL.	Number (double)
service.values.issRetained	Indicador de retenção de ISS.	Boolean
service.values.issRate	Valor da alíquota de ISS.	Number (double)
service.address.street	Logradouro	String (60)
service.address.number	Número	String (10)
service.address.neighborhood	Bairro	String (60)
service.address.cityCode	Código de Município.	String (7)
service.address.city	Município	String (60)
service.address.state	Sigla de Estado	String (2)
service.address.complement	Complemento	String
service.address.zipCode	CEP	String (8)
competenceDate	Data da competência	String
requestId	Identificador único da requisição	String

📘
Caso o rpsSerial e rpsNumber não terem sido informados na criação da empresa, ele deve ser enviado no momento da emissão da Nota Fiscal.

📘
Ao solicitar a emissão da NFs-e, o status de aprovação e os dados dela não são retornados na hora. Isso acontece pois cada prefeitura tem um tempo para processar a solicitação. Não se preocupe, com o webhook cadastrado, assim que a Nota Fiscal ter seu status alterado, iremos enviar os dados da NFs-e na URL configurada.

📘
Os dados do retorno síncrono são apenas para validação da NFs-e emitida.

Modelo de retorno:


{
  "serviceInvoiceId": "6761cf89b9fcb2eb27f9d6af",
  "requestId": "d2e5b7c1-9a3f-4a6e-8f7b-1c9d3b2f6a4e",
  "rpsSerial": 1,
  "rpsNumber": 1,
  "operationType": "TRIBUTACAO_MUNICIPIO",
  "client": {
    "documentType": "CNPJ",
    "document": "51236721000136",
    "name": "Razão Social",
    "cityRegistration": "12345678912345",
    "stateRegistration": "12345678912345",
    "email": "email@google.com",
    "phone": "11912345678",
    "address": {
      "street": "Logradouro",
      "number": "1",
      "neighborhood": "Bairro",
      "cityCode": "3550308",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "complement": "Casa",
      "zipCode": "08190120"
    }
  },
  "service": {
    "cnae": "62091",
    "code": "1.07",
    "cityTaxCode": "3158",
    "cityTaxDescription": "SUPORTE TÉCNICO, MANUTENÇÃO E OUTROS SERVIÇOS EM TECNOLOGIA DA INFORMAÇÃO",
    "description": "Prestação de Serviço",
    "value": 1000,
    "deductionValue": 0,
    "unconditionalDiscount": 0,
    "conditionalDiscount": 0,
    "retentionValue": 0,
    "pisValue": 0,
    "cofinsValue": 0,
    "inssValue": 0,
    "irValue": 0,
    "csllValue": 0,
    "issRetained": true,
    "issRate": 1,
    "baseValue": 1010,
    "issRetainedValue": 10,
    "netValue": 1000,
    "address": {
      "street": "Logradouro",
      "number": "1",
      "neighborhood": "Bairro",
      "cityCode": "3550308",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Casa",
      "zipCode": "08190120"
    }
  },
  "status": "PROCESSING",
  "competenceDate": "2025-02-05T19:57:03.985Z",
  "created": "2025-02-05T19:57:03.985Z"
}

📘
Além dos campos informados na emissão da NFs-e, o retorno da requisição e webhook enviamos dados adicionais. Segue descrição abaixo.

Tabela descritiva dos campos retornados

Campo	Descrição	Tipo
serviceInvoiceId	Identificador da Nota de Serviço.	String
rpsSerial	Série RPS de Documento Fiscal.	String
rpsNumber	Número RPS de Documento Fiscal.	String
status	Status da Nota de Serviço	String
competenceDate	Data de Competência.	String (date-time)
created	Data de Criação.	String (date-time)

Consultar uma NFs-e

Para consultar as suas NFs-e, será necessário realizar uma chamada na api Consultar NFs-e utilizando o método GET, onde na requisição é necessário informar o Identificador da Nota de Serviço.

Modelo de requisição:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/nfse/{id}' \
  -H 'accept: text/plain'

Modelo de retorno:


{
  "requestId": "d2e5b7c1-9a3f-4a6e-8f7b-1c9d3b2f6a4e",
  "rpsSerial": 1,
  "rpsNumber": 1,
  "operationType": "TRIBUTACAO_MUNICIPIO",
  "client": {
    "documentType": "CNPJ",
    "document": "51236721000136",
    "name": "Razão Social",
    "cityRegistration": "12345678912345",
    "stateRegistration": "12345678912345",
    "email": "email@google.com",
    "phone": "11912345678",
    "address": {
      "street": "Logradouro",
      "number": "1",
      "neighborhood": "Bairro",
      "cityCode": "3550308",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "complement": "Casa",
      "zipCode": "08190120"
    }
  },
  "service": {
    "cnae": "62091",
    "code": "1.07",
    "cityTaxCode": "3158",
    "cityTaxDescription": "SUPORTE TÉCNICO, MANUTENÇÃO E OUTROS SERVIÇOS EM TECNOLOGIA DA INFORMAÇÃO",
    "description": "Prestação de Serviço",
    "value": 1000,
    "deductionValue": 0,
    "unconditionalDiscount": 0,
    "conditionalDiscount": 0,
    "retentionValue": 0,
    "pisValue": 0,
    "cofinsValue": 0,
    "inssValue": 0,
    "irValue": 0,
    "csllValue": 0,
    "issRetained": true,
    "issRate": 1,
    "baseValue": 1010,
    "issRetainedValue": 10,
    "netValue": 1000,
    "address": {
      "street": "Logradouro",
      "number": "1",
      "neighborhood": "Bairro",
      "cityCode": "3550308",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Casa",
      "zipCode": "08190120"
    }
  },
  "status": "PROCESSING",
  "number": 0,
  "verificationCode": "0",
  "controlNumber": "20231207000000000099",
  "protocol": "AAAAA6984986",
  "accessKey": "eyjhasgdi5646asdas",
  "linkPdf": "https://blobstorage/pdf",
  "linkXml": ">https://blobstorage/xml",
  "responseCode": "100",
  "responseDescription": "Efetivado",
  "competenceDate": "2025-02-05T20:01:04.439Z",
  "created": "2025-02-05T20:01:04.439Z",
  "updated": "2025-02-05T20:01:04.439Z",
  "serviceInvoiceId": "663167f4fa5fb59547f01ca3"
}

📘
Note que é enviado os dados da NFs-e emitida, além dos campos já preenchidos anteriormente, disponibilizamos o pfd e o xml da nota.

Tabela descritiva dos campos retornados

Campo	Descrição	Tipo
status	Status da Nota de Serviço	String
number	Número de Documento Fiscal	integer (int64)
verificationCode	Código de Verificação	String
controlNumber	Número de Controle	String
protocol	Protocolo de Autorização	String
accessKey	Chave de Acesso	String
linkPdf	Link do documento PDF	String
linkXml	Link do documento XML	String
responseCode	Código de Resposta	String
responseDescription	Descrição de Resposta	String
competenceDate	Data de Competência	String (date-time)
created	Data de Criação	String (date-time)
updated	Data de Atualização	String (date-time)
serviceInvoiceId	Identificador da Nota de Serviço	String

Cancelar uma NFs-e

Para cancelar uma nota fiscal emitida, será necessário realizar uma chamada na api Cancelar NFs-e utilizando o método POST, onde precisa ser preenchido algumas informações relacionadas a NFs-e emitida. Todas as informações necessárias para cancelar uma NFs-e estão no quadro "Parâmetros do Body"

Modelo de requisição:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/nfse/cancel' \
--header 'accept: application/json' \
--header 'Authorization: Bearer acess_token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestId": "9b37e3f9-c59e-4b47-a93e-41f66e89df88",
  "companyId": "6514d4db5f9a3c2e8b1d7f5a",
  "serviceInvoiceId": "6514d4db5f9a3c2e8b1d7f5a"
}
'

Parâmetros do Body:

Campo	Descrição	Tipo
requestId	Identificador único da requisição.	String
companyId	Identificador único da empresa.	String
serviceInvoiceId	Identificador único da nota fiscal.	String

Modelo de retorno:


{
  "id": "663167f4fa5fb59547f01ca3",
  "serviceInvoiceId": "663167f4fa5fb59547f01ca3",
  "requestId": "d2e5b7c1-9a3f-4a6e-8f7b-1c9d3b2f6a4e",
  "status": "PROCESSING",
  "created": "2025-02-05T20:01:35.823Z"
}

📘
Ao cancelar a emissão da NFs-e, ela não é cancelada na hora. Isso acontece pois cada prefeitura tem um tempo para processar a solicitação. Não se preocupe, com o webhook cadastrado, assim que a Nota Fiscal ter seu status alterado, iremos enviar os dados da NFs-e na URL configurada..

Tabela descritiva dos campos retornados

Campo	Descrição	Tipo
id	Identificador do Cancelamento.	String
serviceInvoiceId	Identificador de Nota Fiscal de Serviço.	String
requestId	Identificador de Requisição.	String
status	Tipo de Status.	String
created	Data de Criação.	String (date-time)

Tabela de Erros

Os principais erros de negócio mapeados nas APIs acima estão disponíveis nesse link

Homologação

As instruções para realizar a homologação deste produto estão centralizadas neste link

Sobre a API de Emissão de Nota Fiscal de Serviços (NFs-e)

Caso de uso:

Limitações e exceções:

Cidades Suportadas:

⚠️
Atenção!

Configurando webhook

Modelos de Retorno Webhooks

Registro da NFs-e (invoice-nfse-registration) e Cancelamento da NFs-e (invoice-nfse-cancellation)

📘
Note que o que vai mudar nos cenários de retorno dos webhooks da solicitação de Emissão de uma NFs-e e a Solicitação de Cancelamento de uma NFs-e é o status , que pode assumir o valor de Aprovado "APPROVED" ou cancelado "CANCELED" respectivamente.

Nota Fiscal - Cenário de Erro

📘
Caso ao solicitar a emissão de NFs-e e ela for rejeitada na prefeitura, o retorno do webhook virá com o status de "REJECTED"

Gestão de Empresas

Cadastrar uma empresa para Emissão de NFs-e

Tabela descritiva dos campos retornados

📘
Além dos campos informados na criação, o retorno da requisição enviamos alguns dados adicionais. Segue descrição abaixo

Consultar Empresa Cadastrada

📘
Note que é enviado as informações da empresa cadastrada, inclusive caso já tenha efetuado o cadastro do certificado Digital, ele é informado na consulta de Empresas.

📘
Essa chamada também é síncrona, e na sequência já enviamos as informações sobre a empresa consultada.

Gestão de Certificado

Cadastrar um certificado Digital

📘
Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro do certificado digital.

📘
Os dados do seu certificado estão ficarão em um ambiente seguro e só será utilizado no momento das emissões das suas NFs-e.

Gestão de Notas

Emissão da NFs-e

📘
Caso o rpsSerial e rpsNumber não terem sido informados na criação da empresa, ele deve ser enviado no momento da emissão da Nota Fiscal.

📘
Os dados do retorno síncrono são apenas para validação da NFs-e emitida.

📘
Além dos campos informados na emissão da NFs-e, o retorno da requisição e webhook enviamos dados adicionais. Segue descrição abaixo.

Tabela descritiva dos campos retornados

Consultar uma NFs-e

📘
Note que é enviado os dados da NFs-e emitida, além dos campos já preenchidos anteriormente, disponibilizamos o pfd e o xml da nota.

Tabela descritiva dos campos retornados

Cancelar uma NFs-e

📘
Ao cancelar a emissão da NFs-e, ela não é cancelada na hora. Isso acontece pois cada prefeitura tem um tempo para processar a solicitação. Não se preocupe, com o webhook cadastrado, assim que a Nota Fiscal ter seu status alterado, iremos enviar os dados da NFs-e na URL configurada..

Tabela descritiva dos campos retornados

Tabela de Erros

Homologação

Caso de uso:

Limitações e exceções:

Cidades Suportadas:

⚠️Atenção!

Configurando webhook

Modelos de Retorno Webhooks

Registro da NFs-e (invoice-nfse-registration) e Cancelamento da NFs-e (invoice-nfse-cancellation)

📘Note que o que vai mudar nos cenários de retorno dos webhooks da solicitação de Emissão de uma NFs-e e a Solicitação de Cancelamento de uma NFs-e é o status , que pode assumir o valor de Aprovado "APPROVED" ou cancelado "CANCELED" respectivamente.

Nota Fiscal - Cenário de Erro

📘Caso ao solicitar a emissão de NFs-e e ela for rejeitada na prefeitura, o retorno do webhook virá com o status de "REJECTED"

Gestão de Empresas

Cadastrar uma empresa para Emissão de NFs-e

Tabela descritiva dos campos retornados

📘Além dos campos informados na criação, o retorno da requisição enviamos alguns dados adicionais. Segue descrição abaixo

Consultar Empresa Cadastrada

📘Note que é enviado as informações da empresa cadastrada, inclusive caso já tenha efetuado o cadastro do certificado Digital, ele é informado na consulta de Empresas.

📘Essa chamada também é síncrona, e na sequência já enviamos as informações sobre a empresa consultada.

Gestão de Certificado

Cadastrar um certificado Digital

📘Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro do certificado digital.

📘Os dados do seu certificado estão ficarão em um ambiente seguro e só será utilizado no momento das emissões das suas NFs-e.

Gestão de Notas

Emissão da NFs-e

📘Caso o rpsSerial e rpsNumber não terem sido informados na criação da empresa, ele deve ser enviado no momento da emissão da Nota Fiscal.

📘Os dados do retorno síncrono são apenas para validação da NFs-e emitida.

📘Além dos campos informados na emissão da NFs-e, o retorno da requisição e webhook enviamos dados adicionais. Segue descrição abaixo.

Tabela descritiva dos campos retornados

Consultar uma NFs-e

📘Note que é enviado os dados da NFs-e emitida, além dos campos já preenchidos anteriormente, disponibilizamos o pfd e o xml da nota.

Tabela descritiva dos campos retornados

Cancelar uma NFs-e

📘Ao cancelar a emissão da NFs-e, ela não é cancelada na hora. Isso acontece pois cada prefeitura tem um tempo para processar a solicitação. Não se preocupe, com o webhook cadastrado, assim que a Nota Fiscal ter seu status alterado, iremos enviar os dados da NFs-e na URL configurada..

Tabela descritiva dos campos retornados

Tabela de Erros

Homologação

⚠️
Atenção!

📘
Note que o que vai mudar nos cenários de retorno dos webhooks da solicitação de Emissão de uma NFs-e e a Solicitação de Cancelamento de uma NFs-e é o status , que pode assumir o valor de Aprovado "APPROVED" ou cancelado "CANCELED" respectivamente.

📘
Caso ao solicitar a emissão de NFs-e e ela for rejeitada na prefeitura, o retorno do webhook virá com o status de "REJECTED"

📘
Além dos campos informados na criação, o retorno da requisição enviamos alguns dados adicionais. Segue descrição abaixo

📘
Note que é enviado as informações da empresa cadastrada, inclusive caso já tenha efetuado o cadastro do certificado Digital, ele é informado na consulta de Empresas.

📘
Essa chamada também é síncrona, e na sequência já enviamos as informações sobre a empresa consultada.

📘
Note que essa api é síncrona, sendo assim, a Celcoin irá retornar para você o resultado final da solicitação de cadastro do certificado digital.

📘
Os dados do seu certificado estão ficarão em um ambiente seguro e só será utilizado no momento das emissões das suas NFs-e.

📘
Caso o rpsSerial e rpsNumber não terem sido informados na criação da empresa, ele deve ser enviado no momento da emissão da Nota Fiscal.

📘
Os dados do retorno síncrono são apenas para validação da NFs-e emitida.

📘
Além dos campos informados na emissão da NFs-e, o retorno da requisição e webhook enviamos dados adicionais. Segue descrição abaixo.

📘
Note que é enviado os dados da NFs-e emitida, além dos campos já preenchidos anteriormente, disponibilizamos o pfd e o xml da nota.

📘
Ao cancelar a emissão da NFs-e, ela não é cancelada na hora. Isso acontece pois cada prefeitura tem um tempo para processar a solicitação. Não se preocupe, com o webhook cadastrado, assim que a Nota Fiscal ter seu status alterado, iremos enviar os dados da NFs-e na URL configurada..