integração

Documentação para o Portal do Sacado.

INTRODUÇÃO

Esta seção é destinada aos desenvolvedores dos contratantes para que seja possível criar a integração sistêmica entre a Instituição e a Plataforma da Cessão Digital®. Esta documentação detalha o passo à passo em como criar o acesso ao conjunto de API's, que deverão ser utilizadas para o envio e manutenção dos recebíveis registrados na Plataforma.


CONTRATAÇÃO E ACESSO

O primeiro passo consiste na contratação do serviço, que deverá ser realizada neste endereço.

Uma vez que a contratação esteja devidamente formalizada, a Plataforma enviará por e-mail os dados de acesso, que consiste no código do contratante e na chave de integração. A autenticação deve ser realizada apresentando estes dois códigos, onde elas devem ser informadas para toda e qualquer requisição que seja realizada ao serviço. Você deve informar estas chaves através do header Authorization com o scheme CD-ApiKey, onde o código do contratante deve ser o Username e a chave de integração o Password, separados pelo caractere ":" e codificado em Base64, assim como é mostrado abaixo:


API's

As API's estão divididas em duas categorias, que estão sumarizadas abaixo:

  • Recebíveis: envio e gestão de recebíveis que foram negociados;
  • Financeiro: detalhamento dos planos contratados, fechamentos e faturas do contratante.

Há uma seção totalmente dedicada para a documentação técnica necessária para guiar o desenvolvimento da aplicação consumidora. Esta seção inclui todos os detalhes das API's, incluindo: headers de autenticação, endereço de acesso, parâmetros necessários, objetos de retorno (com seus respectivos schemas) e códigos de erros que eventualmente possam ocorrer.

API's

Endpoints, Estrutura e Schemas.

Clique no botão abaixo para acessar a documentação das API's disponíveis para consumo.

Versão em Uso: v1

RASTREIO DA REQUISIÇÃO

Para fins de auditoria e, principalmente, de depuração, a aplicação consumidora poderá, opcionalmente, adicionar um header nas requisições para identificá-la. Quando estiver presente, esta informação será armazenada juntamente com os logs internos que são gerados, e futuramente, poderá ser utilizado quando houver a necessidade de realizar algum diagnóstico.

Para utilizar este recurso, inclua um header chamado CD-Tracking em todas as requisições enviadas ao serviço. É um campo livre, não obrigatório, onde poderá definir qualquer informação que identifique unicamente a requisição. É importante que se optar por utilizar, mantenha armazenado este identificador para, futuramente, poder correlacionar com os logs internos da Cessão Digital.

Por fim, quando este código estiver presente na requisição, a Cessão Digital o devolverá, também, através do mesmo header na resposta; com isso, a aplicação consumidora poderá realizar alguma consistência sobre ele, como correlacionar as mensagens, armazenamento de logs, etc.


INCLUSÃO DE RECEBÍVEIS

Todos os títulos que forem adquiridos e que se queira incluir na Plataforma, deverá enviar através do método POST para o endpoint de recebíveis, com todos os dados cadastrais, operacionais e de cobrança dos respectivos recebíveis. A documentação da API detalha os campos que são (ou não) obrigatórios; é importante que isso seja honrado, do contrário, a requisição será rejeitada.

Como forma de vínculo entre a base de dados da aplicação consumidora e a Plataforma da Cessão Digital, poderá utilizar o campo UsoDaEmpresa, que é um campo livre que identifica unicamente o recebível para o contratante. Além disso, opcionalmente, poderá também informar Tags contextuais do recebível para caracterizar alguma ação ou operação. Estes dados serão informados sempre que um evento ocorrer sobre aquela recebível.

O endpoint poderá receber múltiplos recebíveis em apenas uma chamada. A aplicação consumidora deverá se atentar ao status de retorno que indicará o sucesso ou a falha no processamento. Se houver algum problema na estrutura da mensagem enviada, será informado o código 400 (Bad Request). Se houver sucesso na análise da mensagem, então os recebíveis são processados de forma síncrona, resultando no status 200 (Ok), porém, é importante se atentar ao conteúdo de retorno devolvido pela API.

Depois de processado, a API devolve uma coleção de objetos do tipo Processamento que traz maiores informações sobre o sucesso ou a falha no processamento e inserção para cada um dos recebíveis postados. Além do Status, Tags e o campo UsoDaEmpresa, há também uma propriedade chamada Codigo que é o identificador (único) que foi atribuído ao recebível. Ele deverá ser armazenado pelo contratante e associado ao respectivo recebível, pois ele deverá ser informando em futuras atualizações, já que é através dele que o recebível é localizado dentro da Plataforma.


ATUALIZAÇÃO DE RECEBÍVEIS

Uma vez que o recebível estiver registrado na Plataforma, compete ao contratante informar toda e qualquer atualização que o recebível tiver. Por atualização, entende-se que seja alguma informação que foi alterada (data de vencimento, parâmetros de protesto, concessão de abatimento, etc.). Além disso, o pagamento, a recompra ou a baixa do recebível também deverá ser reportada, para que o sacado sempre tenha a versão mais atualizada possível.

Essas alterações que ocorrem na base de dados do contratante deverão sempre desencadear para a Plataforma da Cessão Digital uma chamada de atualização dos dados. Elas podem ser individuais ou em lote; para isso, é necessário utilizar o método PUT do endpoint de recebíveis, que, sincronamente, atualizará todas as informações que estiverem divergentes em relação ao registro atual na base da Plataforma. Como dito anteriormente, é obrigatório informar o identificador do recebível na Plataforma através da propriedade Codigo.

De forma análoga ao registro, esta API também retornará o código 400 (Bad Request) se houver algum problema na estrutura da mensagem; caso a mensagem esteja em conformidade, as atualizações serão processadas e resultará no status 200 (OK), onde deverá, da mesma forma, analisar o resultado através da coleção de objetos do tipo Processamento que é devolvido, com o status de atualização para cada recebível postado.


CONCILIAÇÃO DE RECEBÍVEIS

No barramento de API's, a Cessão Digital oferece um serviço que permite relacionar todos os recebíveis que foram incluídos pelo contratante na Plataforma. Este serviço permite para que, pontualmente ou periodicamente, o contratante possa validar se sua base de dados está devidamente sincronizada com as informações que estão vigentes na Plataforma.

Este serviço retorna todos os recebíveis incluídos, porém contendo apenas algumas informações sobre eles: o Codigo (identificar do recebíveis na Plataforma), o UsoDaEmpresa (campo livre que identifica unicamente o recebível para o contratante), o StatusDeCobranca (que indica se o recebível está registrado ou baixado no banco cobrador) e, finalmente, a Situacao (que determina se o título está em aberto, liquidado, baixado ou recomprado).

Caso haja a necessidade de se obter mais informações sobre determinados recebíveis, então é necessário utilizar a API que detalha o mesmo, informando o Codigo do recebível que deseja detalhar.


CALLBACKS E NOTIFICAÇÕES

O processo de notificação do contratante é chamado de Callbacks. Com eles, o contratante pode, opcionalmente, informar uma URL de acesso para que a Plataforma possa notificá-lo sempre que algum evento relevante do processo ocorrer. Isso permitirá ao contratante um controle muito mais refinado, podendo, por exemplo, guiar o andamento de algum processo interno que dependa dos eventos monitorados e gerados por esta Plataforma.

Atualmente a Plataforma é capaz de identificar alguns eventos que ocorrem sobre os recebíveis, sendo eles:

  • Abertura de Chamado: sempre que um sacado abrir um chamado para discutir sobre algum recebível, uma notificação é gerada e encaminhada à respectiva Instituição para tratamento do assunto.
  • Resposta de Chamado: caso um evento já aberto seja respondido, uma notificação é gerada e também encaminhada para a respectiva Instituição.
  • Manifesto do Sacado: toda vez que um sacado se manifestar (positivamente ou negativamente) sobre um determinado recebível (ou sua mercadoria), a notificação é gerada para a Instituição para tratativa do mesmo.
  • CTes Cancelados: Todos os CTes (Conhecimento de Transporte Eletrônico) que estão associados à títulos em aberto são monitorados na SEFAZ quanto ao seu status de cancelamento. Caso seja cancelado, a Plataforma reportará a Instituição incluindo todos os documentos fiscais que tiveram seu status alterado para cancelado.
  • NFes Canceladas: Todos as NFes (Nota Fiscal Eletrônica) que estão associadas à títulos em aberto são monitorados na SEFAZ quanto ao seu status de cancelamento. Caso seja cancelada, a Plataforma reportará a Instituição incluindo todos os documentos fiscais que tiveram seu status alterado para cancelado. Devido à falta de padronização por parte das Prefeituras, Notas Fiscais de Serviço não são monitoradas.

SUPORTE

Caso esta documentação não tenha sido suficiente para esclarecer suas dúvidas ou houve alguma dificuldade em realizar a integração, entre em contato através deste formulário ou via WhatsApp através do telefone (19) 9.9901-1065, para, muito brevemente, entrarmos em contato para tentar esclarecer e sanar suas dúvidas. Utilize este mesmo canal se desejar nos enviar alguma crítica ou sugestão.