Criação de API para Disponibilização de Prospects e Pedidos (JSON)
Histórico de Alterações
| Data | Quem | Comentários |
|---|---|---|
| 17/09/2025 | Renato Lima | Criação do documento |
Necessidade
O contratante identificou a necessidade de integrar os dados de clientes prospect e de pedidos/orçamentos com o sistema de CRM. Essa integração tem como objetivo otimizar o fluxo comercial, permitindo que as informações registradas na aplicação atual sejam automaticamente enviadas ao CRM, garantindo maior eficiência no acompanhamento das oportunidades, além de evitar retrabalho e inconsistências entre os sistemas.
Solução
Para atender a essa necessidade, será disponibilizada uma API em formato JSON, por meio da qual os dados de clientes prospect e de pedidos/orçamentos poderão ser consumidos pelo CRM. A estrutura da API seguirá um modelo previamente definido, garantindo padronização, segurança e escalabilidade. Essa solução permitirá a automatização da integração, assegurando flexibilidade para futuras evoluções e ampliações no processo.
• Disponibilização dos dados de clientes prospect e pedidos/orçamentos em formato JSON através da API.
• Definição do modelo de dados e estrutura de integração.
• Implementação de mecanismos básicos de autenticação e segurança de acesso à API.
- Dados que devem ser enviados referente ao pedido
| Campo CRM | Campo GeoSales | Observações |
|---|---|---|
| DATA ULTIMA ATUALIZACAO | DT_UPDATE(PEDIDO) | Data de referencia para identificar que houve atualização no registro |
| ID ORÇAMENTO | CD_PEDIDO_PALM(PEDIDO) | Cód do pedido ou Orçamento |
| CNPJ | NR_CNPJ_CPF(CLIENTE) | Número do CPF/CNPJ |
| NOME / RAZAO SOCIAL | NM_CLIENTE/NM_FANTASIA(CLIENTE) | Nome do cliente |
| ID ERP TOTVS | CD_CLIENTE_REFERENCIA(CLIENTE) | cod de identificação do cliente |
| ID GEOSALES do CLIENTE/PROSPECT | CD_CLIENTE(CLIENTE_APROVACAO,CLIENTE) | Cod identificação do Cliente Geosales |
| DATA CRIACAO ORÇAMENTO | DT_EMISSAO(PEDIDO) | Data de emissão do pedido |
| VALOR ORÇAMENTO | VR_PEDIDO (PEDIDO) | Valor do Pedido |
| SITUACAO ORCAMENTO | CD_ST_SITUACAO(PEDIDO) | Situação do pedido |
| DATA PREVISAO ORÇAMENTO | DT_VENCIMENTO(PEDIDO) | Campo de vencimento do pedido. |
| CALOR % PROBABILIDADE | CD_MOTIVO PEDIDO - DS_MOTIVO(PEDIDO) | Campo de seleção para motivo, será usado para informar esta probabilidade |
| MEIO PAGAMENTO | CD_MEIO_PGTO(PEDIDO) | Meio de pagamento do pedido |
| CONDICAO PAGAMENTO | CD_COND_PGTO(PEDIDO) | Condição de pagamento do pedido |
| FRETE | ID_TIPO_FRET | Tipo do frete (PEDIDO) |
| TRANSPORTADORA | CD_TRANSPORTADORA(PEDIDO) | Transportadora |
| ID PEDIDO | CD_PEDIDO_PALM (PEDIDO) | Cod do pedido |
| DT CRIACAO do PEDIDO | DT_EFETIVACAO(PEDIDO) | Data que pedido foi efetivado |
| SITUAÇÃO PEDIDO | CD_ST_PEDIDO | Situação do pedido é a mesma que tem acima, só muda o status |
| ID VEDEDOR/REPRESENTANTE | CD_VENDEDOR(PEDIDO) | Identificação do vendedor |
| NOME DO VENDEDOR/REPRESENTANTE | NM_VENDEDOR(VENDEDOR) | Nome do Vendedor |
| DATA CANCELAMENTO | DT_CANCELAMENTO(PEDIDO) | data que orçamento foi cancelado |
| MOTIVO CANCELAMENTO | CD_MOTIVO_CANCELAMENTO(PEDIDO) | Motivo do cancelamento |
- Informações do Item
| Campo CRM | Campo GeoSales | Observações |
|---|---|---|
| COD_PEDIDO | CD_PEDIDO_PALM | Codigo do pedido que as famílias pertencem |
| FAMILIA | CD_FAMILIA | Data de referencia para identificar que houve atualização no registro |
| QUANTIDADE_ITENS | Quantidade de itens total da Família | Quantidade de itens da família |
| VALOR_TOTAL | VR_ITENS | Valor total dos itens da familia |
- Informações da Nota fiscal
| Campo CRM | Campo GeoSales | Observações |
|---|---|---|
| COD_PEDIDO | CD_PEDIDO_PALM(PEDIDO_NOTA_FISCAL) | Numero da Nota fiscal |
| NOTA FISCAL (Quando faturado) | CD_NOTA_FISCAL (NOTA_FISCAL) | Numero da Nota fiscal |
| DATA NOTA FISCAL | DT_EMISSAO (NOTA FISCAL) | Data da emissão da nota fiscal |
Devemos disponibilizar todas as informações de CLIENTE_APROVACAO, já as das tabela PEDIDO, ITEM_PEDIDO E NOTA FISCAL fiz um de/para, que adicionei os campos em tabelas acima que são esperados para receber no CRM.
Regras de Negócio
[RN1] - A API deve disponibilizar apenas os dados de clientes prospect, pedidos/orçamentos, Item em orçamento, status de atualização quando forem cancelado e se foram faturados e que estejam devidamente cadastrados e ativos no sistema de origem.
[RN2] - A API deve disponibilizar sempre os dados atualizados do sistema de origem. Qualquer alteração em prospects ou pedidos refletirá automaticamente nos dados expostos pela API.
[RN3] - Todos os dados expostos devem seguir o padrão JSON, estruturado conforme o modelo previamente definido.
[RN4] - A responsabilidade pelo consumo, tratamento e armazenamento dos dados é do sistema CRM. A API não realiza transformações ou persistência fora do escopo definido.
[RN5] - A API deve estar disponível em regime contínuo, salvo em períodos de manutenção programada.
[RN6] - A API, deve disponibilizar os dados de CLIENTE_APROVACAO,PEDIDO,ITEM e NOTAL FISCAL.
[RN7] - Uma vez que um pedido for realizado e ele for criado e efetivado na mesma ação, este deve está disponível nos dados que serão enviados ao ERP e CRM.
Anexos
Aprovação
Considero aprovada a documentação da funcionalidade especificada acima, e autorizo a implementação da mesma no Sistema GeoSales, em nome da Organização a qual estou vinculado.
GeoSales
| Setor | Aprovado Por | Data |
|---|---|---|
| Desenvolvimento - GeoSales | Pessoa que aprovou | 00/00/0000 |
| Integração - GeoSales | Pessoa que aprovou | 00/00/0000 |
| Configurações - GeoSales | Pessoa que aprovou | 00/00/0000 |
Empresa solicitante
| Setor | Aprovado Por | Data | Assinatura |
|---|---|---|---|
| Gerente TI - Cliente | Pessoa que aprovou | 00/00/0000 | |
| Gerente de Projeto - Cliente | Pessoa que aprovou | 00/00/0000 | |
| Gerente Comercial - Cliente | Pessoa que aprovou | 00/00/0000 |