Visão geral da API

Esta seção foi escrita para administradores e desenvolvedores de integrações — o único canto desta base de conhecimento onde nomes de classes Apex têm lugar.

A REDA Financials é nativa do Salesforce até a raiz: todo documento é um objeto personalizado, toda contabilização é uma mudança de estado disparada por trigger, e por isso toda API padrão do Salesforce funciona sobre os seus dados contábeis prontamente. Além dessa superfície da plataforma, o pacote expõe um conjunto pequeno e deliberado de contratos estáveis. Esta visão geral mapeia todo o panorama de integração.

As quatro camadas de integração

Tudo o que é incluído — e tudo o que deliberadamente não é

O planejamento de integrações começa com um inventário honesto. Aqui está a superfície empacotada completa — e, tão útil quanto isso, as coisas que você poderia procurar e que não estão lá, porque a plataforma padrão já as fornece:

A superfície global de Apex — a lista completa

Treze tipos globais constituem o contrato Apex estável do pacote. Cinco são os pontos de entrada do dia a dia:

• refin.GlobalTaxService — calcula imposto indireto e retenção na fonte de forma programática, sem DML, com resultados totalmente resolvidos contra o livro razão.
• refin.PDFGeneratorAPI — gera o PDF de um documento a partir de Apex ou Fluxo.
• refin.BankFeedProvider — o contrato abstrato que os pacotes de extensão de feed bancário implementam.
• refin.EInvoiceProvider — o contrato abstrato que os provedores de fatura eletrônica implementam.
• refin.OCREmailHandler — o manipulador de e-mail de entrada por trás da automação de e-mail para fatura; aponte um Email Service para ele.

Os oito restantes existem para os pacotes de extensão: os contratos de nota fiscal eletrônica e os tipos que eles trocam, mais dois pontos de entrada que você chama diretamente:

• refin.EInvoiceQueueProvider, refin.EInvoiceDocumentProvider, refin.EInvoiceProvisioner — interfaces globais adicionadas ao lado de EInvoiceProvider, porque uma classe abstrata global já publicada não pode ganhar métodos sem quebrar os pacotes que já a estendem.
• refin.EInvoiceDocument, refin.EInvoiceEvent, refin.EInvoiceProvisionResult — os tipos de transferência de dados que esses contratos recebem e devolvem.
• refin.EInvoiceStatusPollSchedulable — agende a consulta de status de nota fiscal eletrônica no seu próprio cron em vez do cartão do Console de administração.
• refin.EInvoiceTrailCreator — crie uma trilha de nota fiscal eletrônica para faturas de venda contabilizadas; também exposta como ação de Flow.

Tudo o mais no pacote é public — interno, invisível entre namespaces, e sujeito a mudanças. Se uma classe não estiver nesta lista, não construa nada dependente dela.

Serviços internos não são API — mesmo quando você consegue vê-los

Ao ler logs de depuração e conjuntos de permissões, você encontrará classes de serviço internas por trás de ações do dia a dia — contabilização, renderização de PDF, importação de extrato bancário, chamadas de IA e de câmbio, carga inicial de conteúdo fiscal. Elas são public, não global — o Apex de assinantes e extensões não pode chamá-las através da fronteira do namespace, e sua forma interna pode mudar em qualquer versão, então nada do que você construir deve referenciá-las pelo nome:

Versionamento e segurança em atualizações

As classes de API do pacote são compiladas na versão 65.0 da API do Salesforce — refin.GlobalTaxService se declara "@since API v65.0". A regra dos pacotes gerenciados é a espinha dorsal do seu planejamento:

• Global é para sempre: uma vez publicadas, classes, métodos e variáveis de membro globais não podem ser removidos nem ter suas assinaturas alteradas pelo publicador. Os treze tipos acima, as ações de Fluxo que eles expõem, e todo objeto e campo refin__ publicado são a sua superfície estável.
• Public é privado, na prática: classes internas podem ser renomeadas, remodeladas ou excluídas em qualquer versão — e como são invisíveis entre namespaces, nada do que você publica pode quebrar por depender delas, porque nada do que você publica pode depender delas.
• O comportamento viaja através dos triggers: todos os 52 triggers empacotados executam sobre o DML da API de forma idêntica em todas as atualizações — não há flag de bypass a perder, nem modo especial a retestar.

Uma integração típica, em linhas gerais

O sistema de gestão de propriedades da Meridian Properties Group fatura os locatários; a REDA mantém a contabilidade. A integração noturna se autentica através do próprio connected app da Meridian como um usuário de integração que possui Accounts Receivable, insere cada fatura como um refin__Sales_Invoice__c em rascunho com suas linhas, e depois atualiza cada uma para Posted em uma segunda chamada. Os números de documento são atribuídos a partir das sequências da entidade na inserção, os valores padrão da entidade são preenchidos, e a contabilização executa o motor completo — impostos, taxas de câmbio, validações de período. Quando um registro falha (um período fechado, por exemplo), a mensagem de erro que a API retorna é a mesma frase que um usuário leria na tela, o que torna as conversas de suporte curtas. Código personalizado total na REDA: nenhum.

O único princípio que torna a integração fácil

A API e a interface são a mesma máquina. Insira uma fatura em rascunho via REST e ela recebe seu número de documento, valores padrão da entidade e validações exatamente como se tivesse sido digitada. Atualize seu status para Posted e o motor de contabilização completo é executado — impostos, retenções, taxas de câmbio, todas as validações. Não existe uma porta dos fundos para integrações, o que significa que não há nada de especial a aprender: o que um usuário pode fazer, um usuário de API pode fazer, sob as mesmas regras e os mesmos conjuntos de permissões.

O que vem a seguir

1. API REST para dados contábeis — a integração do primeiro dia.
2. Desenvolvimento em Apex na REDA — as classes globais em detalhe.
3. Pacotes de extensão — os contratos de provedor.

Perguntas frequentes