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 | Data de referencia para identificar que houve atualização no registro |
| ID ORÇAMENTO | CD_PEDIDO_PALM | Cód do pedido ou Orçamento |
| CNPJ | NR_CNPJ_CPF | Número do CPF/CNPJ |
| NOME / RAZAO SOCIAL | NM_CLIENTE/NM_FANTASIA | Nome do cliente |
| ID ERP TOTVS | CD_CLIENTE_REFERENCIA | cod de identificação do cliente |
| ID GEOSALES do CLIENTE/PROSPECT | CD_CLIENTE | Cod identificação do Cliente Geosales |
| DATA CRIACAO ORÇAMENTO | DT_EMISSAO | Data de emissão do pedido |
| VALOR ORÇAMENTO | VR_PEDIDO | Valor do Pedido |
| SITUACAO ORCAMENTO | CD_ST_SITUACAO | Situação do pedido |
| DATA PREVISAO ORÇAMENTO | DT_VENCIMENTO | Campo de vencimento do pedido. |
| CALOR % PROBABILIDADE | CD_MOTIVO PEDIDO - DS_MOTIVO | Campo de seleção para motivo, será usado para informar esta probabilidade |
| MEIO PAGAMENTO | CD_MEIO_PGTO | Meio de pagamento do pedido |
| CONDICAO PAGAMENTO | CD_COND_PGTO | Condição de pagamento do pedido |
| FRETE | ID_TIPO_FRET | Tipo do frete |
| TRANSPORTADORA | CD_TRANSPORTADORA | Transportadora |
| ID PEDIDO | CD_PEDIDO_PALM | Cod do pedido |
| DT CRIACAO do PEDIDO | DT_EFETIVACAO | 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 | Identificação do vendedor |
| NOME DO VENDEDOR/REPRESENTANTE | NM_VENDEDOR | Nome do Vendedor |
| DATA CANCELAMENTO | DT_CANCELAMENTO | data que orçamento foi cancelado |
| MOTIVO CANCELAMENTO | CD_MOTIVO_CANCELAMENTO | Motivo do cancelamento |
| NF (Quando faturado) | CD_NOTA_FISCAL | Numero da Nota fiscal |
| DT NF | DT_EMISSAO(NOTA FISCAL) | Data da emissaão da nota fiscal |
- 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 |
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.
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 |