SankhyaAPI.Client
6.0.0
dotnet add package SankhyaAPI.Client --version 6.0.0
NuGet\Install-Package SankhyaAPI.Client -Version 6.0.0
<PackageReference Include="SankhyaAPI.Client" Version="6.0.0" />
<PackageVersion Include="SankhyaAPI.Client" Version="6.0.0" />
<PackageReference Include="SankhyaAPI.Client" />
paket add SankhyaAPI.Client --version 6.0.0
#r "nuget: SankhyaAPI.Client, 6.0.0"
#:package SankhyaAPI.Client@6.0.0
#addin nuget:?package=SankhyaAPI.Client&version=6.0.0
#tool nuget:?package=SankhyaAPI.Client&version=6.0.0
👜 SankhyaAPI.Client
Biblioteca .NET para integração com o ERP Sankhya: CRUD de entidades, consultas, SQL cru, relatórios, sessões e telemetria.
A 6.0 quebra a API da 5.x e não tem camada de compatibilidade. Para migrar, siga o guia de migração 5.x → 6.0. O histórico de mudanças está no CHANGELOG.
Índice
- Instalação
- Configuração
- Sessão
- Mapeamento
- CRUD
- Atualização parcial
- Consultas
- SQL cru
- Relatórios
- Erros
- Observabilidade
- Resiliência
- Source generator e AOT
- Testes
- Skill para agentes de IA
- Licença
Instalação
dotnet add package SankhyaAPI.Client --version 6.0.0
O pacote tem como alvo net8.0 e net10.0.
Configuração
O pacote foi feito para injeção de dependência, mas também funciona sem ela.
Com injeção de dependência
Em appsettings.json, sem a senha:
{
"Sankhya": {
"BaseUrl": "https://erp.empresa.com.br/mge",
"Usuario": "integracao",
"SessionMode": "Shared",
"MaxSessions": 4
}
}
A senha não fica no arquivo. Em desenvolvimento, use user-secrets; em produção, o cofre de segredos ou variável de ambiente:
dotnet user-secrets set "Sankhya:Senha" "<senha>"
No Program.cs:
using SankhyaAPI.Client;
builder.Services
.AddSankhya(o => builder.Configuration.GetSection("Sankhya").Bind(o))
.AddEntity<Produto, ProdutoMap>() // mapa fluente
.AddRepository<Parceiro>("Parceiro"); // mapa por atributos
O Bind vem de Microsoft.Extensions.Configuration.Binder, que o host do ASP.NET Core e o Generic Host já trazem. Quem consome recebe o repositório pela injeção:
public class ProdutoService(ISankhyaRepository<Produto> produtos)
{
public Task<Produto?> ObterAsync(long codigo, CancellationToken ct = default) =>
produtos.GetAsync([codigo], ct);
}
AddSankhya valida as opções na inicialização (ValidateOnStart): uma opção inválida impede o host de subir.
Sem injeção de dependência
using SankhyaAPI.Client;
await using SankhyaClient sankhya = SankhyaClient.Create(new SankhyaClientOptions
{
BaseUrl = "https://erp.empresa.com.br/mge",
Usuario = "integracao",
Senha = senha, // de cofre ou user-secrets, nunca fixa no código
});
SankhyaMaps.Register<ProdutoMap>();
ISankhyaRepository<Produto> produtos = sankhya.Repository<Produto>();
SankhyaClient.Create aceita um ILoggerFactory opcional. SankhyaMaps.Register registra o mapa no processo inteiro: vale para todos os clientes.
Opções
| Opção | Padrão | Descrição |
|---|---|---|
BaseUrl |
obrigatória | URL absoluta do Sankhya, terminada em /mge. Exemplo: https://erp.empresa.com.br/mge. |
Usuario |
obrigatória | Usuário de integração. |
Senha |
obrigatória | Senha do usuário. Leia de cofre ou user-secrets. |
SessionMode |
Shared |
Shared ou PerOperation (ver Sessão). |
MaxSessions |
4 |
Máximo de sessões abertas no modo Shared. Também é o máximo de chamadas em paralelo. |
Timeout |
100 s | Tempo máximo de cada tentativa de chamada a um serviço. |
MaxRetries |
2 |
Novas tentativas em falha transitória, só em operações idempotentes (ver Resiliência). |
Dialect |
SqlServer |
Banco por trás do Sankhya (SqlServer ou Oracle), usado para formatar valores no SQL cru. |
VerifyExistenceOnUpdate |
true |
Confere se as chaves existem antes de cada update. O saveRecord do Sankhya cria o registro quando a chave não existe; com a opção ligada, o update lança SankhyaNotFoundException. Custa uma consulta por lote. |
AllowHttp |
false |
Libera http://. Só para desenvolvimento: a senha e a sessão trafegam em texto puro. |
Opções inválidas lançam OptionsValidationException com a lista de problemas: BaseUrl absoluta e terminada em /mge, https (salvo AllowHttp), Usuario e Senha preenchidos, Timeout positivo, MaxRetries não negativo e MaxSessions de pelo menos 1.
Sessão
O Sankhya recusa duas requisições simultâneas na mesma sessão, com a mensagem "O serviço foi cancelado por situação de concorrência". Por isso o pacote dá a cada operação uma sessão com exclusividade.
| Modo | Como funciona | Quando usar |
|---|---|---|
Shared (padrão) |
Login sob demanda. Até MaxSessions sessões ficam abertas e são reaproveitadas, uma operação por vez em cada uma. Chamadas além desse limite esperam. |
Uso normal, com várias chamadas. |
PerOperation |
Login e logout em cada operação, como na 5.x. | Isolamento total, ou jobs que rodam de tempos em tempos. |
No modo Shared, quando o Sankhya responde que a sessão expirou (status="3"), o pacote abre outra sessão e repete a operação uma vez. Repetir uma escrita é seguro nesse caso: com a sessão expirada, o Sankhya não grava nem apaga nada.
As sessões compartilhadas são encerradas no DisposeAsync do SankhyaClient. Com injeção de dependência, elas são encerradas quando o contêiner é descartado de forma assíncrona (await using no ServiceProvider, ou o host da aplicação), porque o tipo implementa só IAsyncDisposable.
Sessão explícita
Quando um fluxo precisa de várias chamadas na mesma sessão, abra-a explicitamente. O login usa as credenciais da configuração:
SankhyaSessionInfo sessao = await sankhya.Session.LoginAsync(ct);
// Enquanto a sessão estiver aberta, todas as operações a usam, uma por vez.
List<Produto> ativos = await produtos.FindAsync("this.ATIVO = 'S'", ct);
await sankhya.Session.LogoutAsync(ct);
Com injeção de dependência, ISankhyaSession é singleton. Enquanto uma sessão explícita estiver aberta, todas as operações da aplicação passam por ela, uma por vez. Use esse fluxo em jobs e rotinas curtas, não em requisições web concorrentes.
Chamada a um serviço que o pacote não cobre
sankhya.Transport expõe a chamada crua ao service.sbr. Ela precisa da sessão, então roda dentro de Session.ExecuteAsync. O corpo (requestBody) é montado pelo chamador:
using System.Xml.Linq;
using SankhyaAPI.Client.Transport;
List<XElement> corpo = [new XElement("dataSet", new XAttribute("rootEntity", "Produto"))];
SankhyaXmlResponse resposta = await sankhya.Session.ExecuteAsync(
(id, token) => sankhya.Transport.SendXmlAsync(SankhyaServices.LoadRecords, corpo, id, idempotent: true, token),
ct);
Mapeamento
Há dois jeitos de dizer como um modelo vira uma entidade do Sankhya. O mapa fluente mantém o modelo limpo, sem atributos, e é o recomendado. Os atributos servem para casos simples.
Mapa fluente
using SankhyaAPI.Client.Mapping;
public class Produto
{
public long CodProd { get; set; }
public string? DescrProd { get; set; }
public decimal? Preco { get; set; }
public DateTime? DtAlter { get; set; }
public bool? Ativo { get; set; }
public string? NomeGrupo { get; set; }
}
public sealed class ProdutoMap : SankhyaEntityMap<Produto>
{
public ProdutoMap()
{
Entity("Produto");
Key(x => x.CodProd, "CODPROD").AutoNumbered();
Property(x => x.DescrProd, "DESCRPROD");
Property(x => x.Preco, "PRECO");
Property(x => x.DtAlter, "DTALTER");
Property(x => x.Ativo, "ATIVO");
Presentation(x => x.NomeGrupo, "GrupoProduto_DESCRGRUPOPROD"); // campo de apresentação, só leitura
}
}
Outros recursos do mapa, com um modelo de exemplo:
public enum StatusOs { Aberta, Fechada }
public class OrdemServico
{
public int Numero { get; set; }
public string? Descricao { get; set; }
public DateTime? DataExecucao { get; set; }
public StatusOs Status { get; set; }
public string? NomeParceiro { get; set; }
public string? NomeUsuario { get; set; }
}
public sealed class OrdemServicoMap : SankhyaEntityMap<OrdemServico>
{
public OrdemServicoMap()
{
Entity("OrdemServico");
Key(x => x.Numero, "NUMOS").AutoNumbered();
Property(x => x.Descricao, "DESCRICAO");
Property(x => x.Status, "STATUS").Options(("A", StatusOs.Aberta), ("F", StatusOs.Fechada));
Computed(x => x.DataExecucao)
.Writes("DT_FINAL", SankhyaType.Date)
.Writes("HR_FINAL", SankhyaType.Time)
.Reads<DateOnly?, TimeOnly?>("DT_FINAL", "HR_FINAL", (d, h) => d?.ToDateTime(h ?? TimeOnly.MinValue));
Joined(x => x.NomeParceiro, "Parceiro", "NOMEPARC");
Presentation(x => x.NomeUsuario, "Usuario_NOMEUSU");
}
}
| Método | O que faz |
|---|---|
Entity("Nome") |
Nome da entidade (instância) no Sankhya, por exemplo Produto. |
Key(x => x.Campo, "COLUNA") |
Campo da chave. Chave composta: chame uma vez por campo. .AutoNumbered() marca o campo que o servidor gera no insert. Só um campo por chave pode ser auto-numerado. |
Property(x => x.Campo, "COLUNA") |
Campo lido e escrito na coluna. Aceita um SankhyaType explícito, .Options(("código", valor), ...) para listas de opções, .ReadOnly() e um ISankhyaConverter<T> próprio. |
Computed(x => x.Campo) |
Campo do domínio que ocupa mais de uma coluna. .Writes(coluna, tipo) pode aparecer várias vezes. Para ler, .Reads<T1>(coluna, compor) ou .Reads<T1, T2>(coluna1, coluna2, compor). Sem Reads, o campo é só de escrita. |
Joined(x => x.Campo, "Caminho", "CAMPO") |
Campo de entidade ligada, só leitura. Pede <entity path="Caminho"> e lê a coluna Caminho_CAMPO. |
Presentation(x => x.Campo, "Coluna") |
Campo de apresentação que o Sankhya acrescenta, só leitura. Só os mapas com campo de apresentação pedem includePresentationFields. |
Coluna escrita por dois campos é erro, e uma chave precisa corresponder a exatamente uma coluna. O mapa é validado quando é usado pela primeira vez. Para validar antes, na inicialização, chame SankhyaMaps.Validate<T>().
Quando o tipo não é dado com SankhyaType, ele é inferido pelo tipo da propriedade (também dentro de Nullable<> e NullableState<>):
| Tipo .NET | Sankhya | Formato no XML |
|---|---|---|
string, char, Guid |
Texto (S) |
sem espaços nas pontas |
int, long, short, byte e equivalentes sem sinal |
Inteiro (I) |
número |
decimal, double, float |
Decimal (F) |
ponto decimal, cultura invariante |
DateOnly |
Data (D) |
dd/MM/yyyy |
DateTime, DateTimeOffset |
Data e hora (H) |
dd/MM/yyyy HH:mm:ss |
TimeOnly |
Hora (T) |
HHMM, como número (smallint) |
bool |
Sim/não | S ou N |
enum |
Lista de opções | código do [XmlEnum], ou do .Options(...) |
Texto vazio vira null na leitura (sim/não vira false). Erro de conversão lança FormatException sem o valor na mensagem (ver Erros).
Para um formato que a tabela não cobre, implemente ISankhyaConverter<T>: Format(T) devolve o texto a enviar (ou null), e Parse(string) devolve o valor a partir de um texto que nunca chega vazio.
Mapa por atributos
using System.Xml.Serialization;
using SankhyaAPI.Client.Mapping;
[SankhyaEntity("ItemNota")]
public class ItemNota
{
[Key("NUNOTA")] public long NuNota { get; set; }
[Key("SEQUENCIA", true)] public int Sequencia { get; set; }
[XmlElement("QTDNEG")] public decimal Quantidade { get; set; }
[SankhyaPresentation("Produto_DESCRPROD")] public string? DescrProduto { get; set; }
}
Propriedades sem [XmlElement], [Key] ou [SankhyaPresentation] não entram no mapa. Campo calculado, entidade ligada e opções exigem o mapa fluente. Propriedades NullableState<T> também funcionam nos dois mapas (ver Atualização parcial).
CRUD
Os métodos ficam em ISankhyaRepository<T>, obtido com sankhya.Repository<T>() ou pela injeção:
Produto novo = new() { DescrProd = "Parafuso", Preco = 1.5m, Ativo = true };
await produtos.CreateAsync(novo); // novo.CodProd recebe a chave gerada pelo Sankhya
List<Produto> lote = [new() { DescrProd = "Porca" }, new() { DescrProd = "Arruela" }];
await produtos.CreateManyAsync(lote);
Produto? encontrado = await produtos.GetAsync([novo.CodProd]);
await produtos.DeleteAsync(novo);
await produtos.DeleteManyAsync(lote);
| Método | O que faz |
|---|---|
CreateAsync(entidade), CreateManyAsync(entidades) |
Insere e devolve o que foi gravado. A chave gerada é preenchida no próprio objeto. |
GetAsync(object[] chave) |
Busca pela chave, com os valores na ordem dos campos da chave no mapa. Devolve null se não existir. |
FindAsync(expressao) |
Filtro sem parâmetros. Traz todos os registros que atendem, sem limite. Não concatene valores vindos do usuário. |
FindAsync(expressao, parametros, ordenacao) |
Filtro com ? para cada valor, e ordenação opcional. |
FindPageAsync(expressao, parametros, pagina, ordenacao) |
Uma página de até 50 registros, começando em 0. |
UpdateAsync, UpdateManyAsync, UpdateAllAsync, Track |
Atualização (ver Atualização parcial). |
DeleteAsync(entidade), DeleteManyAsync(entidades) |
Exclui pela chave. |
Query() |
Consulta fluente (ver Consultas). |
Filtro com parâmetros, em que os valores não viram SQL:
using SankhyaAPI.Client.Repositories;
string padrao = busca + "%";
List<Produto> produtosDoGrupo = await produtos.FindAsync(
"this.DESCRPROD LIKE ? AND this.ATIVO = ?",
[Parameter.Texto(padrao), Parameter.Texto("S")],
"this.CODPROD");
Regras de chave, verificadas antes de enviar: no insert, a chave sem auto-numeração precisa estar preenchida, e a auto-numerada precisa estar com o valor padrão (zero, ou null em tipo anulável), porque o servidor a gera. Update e delete exigem a chave.
Em modelo POCO, todo campo de tipo de valor não anulável (int, bool, DateTime sem ?) vai no insert, mesmo com o valor padrão. Para não enviar um campo, use o tipo anulável ou NullableState<T>.
Atualização parcial
Um update manda só o que foi informado: a chave e os campos escolhidos. Campo apagado vai vazio. Há três formas, e as três mandam o mesmo tipo de envelope.
1. Campos explícitos (padrão). Você diz quais campos mandar:
await produtos.UpdateAsync(
new Produto { CodProd = 10, DescrProd = "Parafuso M8" },
u => u.Set(x => x.DescrProd).Clear(x => x.Preco));
Set manda o valor atual do campo. Se o valor for null, nada é enviado para o campo; para apagar, use Clear.
2. Rastreamento (Track). O pacote guarda uma cópia do estado lido, e o update manda só o que mudou. Um campo que virou null é apagado:
Produto? atual = await produtos.GetAsync([10L]);
if (atual is null) return;
Produto produto = produtos.Track(atual);
produto.DescrProd = "Parafuso M8 zincado";
produto.Preco = null; // vira Clear: apaga no servidor
await produtos.UpdateAsync(produto); // manda só DESCRPROD e PRECO
Depois de salvar, o objeto volta a ser rastreado a partir do novo estado.
3. NullableState<T> no modelo. Cada propriedade guarda se foi informada, apagada ou não. Ela é imutável: troque o valor por atribuição, ou use NullableState<T>.Set(v), NullableState<T>.Clear() e NullableState<T>.Unset (não mexe no campo, e é o padrão):
[SankhyaEntity("Produto")]
public class ProdutoAtualizavel
{
[Key("CODPROD", true)] public NullableState<long> CodProd { get; set; }
[XmlElement("DESCRPROD")] public NullableState<string> DescrProd { get; set; }
[XmlElement("PRECO")] public NullableState<decimal> Preco { get; set; }
}
ISankhyaRepository<ProdutoAtualizavel> repo = sankhya.Repository<ProdutoAtualizavel>();
var produto = new ProdutoAtualizavel { CodProd = 10, DescrProd = "Parafuso M8" };
produto.Preco = NullableState<decimal>.Clear();
await repo.UpdateAsync(produto);
Atualizar todos os campos. UpdateAllAsync(entidade) manda todos os campos mapeados, e valor null é apagado. Isso sobrescreve alterações que outros fizeram no Sankhya, então use só quando for o que você quer.
UpdateAsync(entidade) sem Track e sem propriedades NullableState<T> lança InvalidOperationException: informe os campos, rastreie o objeto ou use UpdateAllAsync.
Consultas
Query() devolve um SankhyaQuery<T>, que monta o loadRecords de forma fluente:
using SankhyaAPI.Client.Repositories;
await foreach (Produto p in produtos.Query()
.Where("this.ATIVO = ? AND this.PRECO > ?", "S", 10m)
.OrderBy(x => x.CodProd)
.StreamAsync(ct))
{
// um registro por vez; o pacote pede 50 por página
}
SankhyaPage<Produto> pagina = await produtos.Query()
.Where("this.ATIVO = ?", "S")
.OrderBy(x => x.CodProd)
.ToPageAsync(0, ct);
List<Produto> todos = await produtos.Query().ToListAsync(ct); // tudo em memória, sem limite
| Método | O que faz |
|---|---|
Where(expressao, valores...) |
Filtro com ? para cada valor. Vários Where se combinam com AND. O tipo do valor é inferido: texto, inteiro, decimal, data, data e hora, sim/não (S/N) ou código de enum. Erro se a quantidade de ? não bater com a de valores. |
OrderBy(x => x.Campo), OrderByDescending(x => x.Campo) |
Ordenação pela coluna mapeada da propriedade. Não aceita texto livre. |
ModifiedSince(DateTime) |
Só os registros alterados desde a data. Exige o parâmetro LOGTABOPER habilitado no Sankhya; sem ele, o servidor responde CORE_E07537. |
IgnoreCalculatedFields() |
Pede ignoreCalculatedFields. O efeito sobre campos calculados não foi constatado na homologação. |
FileBasedPagination() |
Pede useFileBasedPagination. O servidor aceita, sem efeito observável na homologação. |
ToListAsync() |
Todos os registros em memória, sem limite. |
ToPageAsync(pagina) |
Uma página de até 50 registros, começando em 0. |
StreamAsync() |
IAsyncEnumerable<T> que pede as páginas em sequência até o Sankhya informar que não há mais. |
FirstOrDefaultAsync() |
Primeiro registro da primeira página, pela ordenação. null se não houver. |
O StreamAsync usa uma ordenação estável: informe um OrderBy pela chave. O resultado não é um retrato fixo; se os dados mudarem durante a leitura, a paginação pode repetir ou pular registros.
Os valores do Where vão como <parameter>, separados da expressão. O comportamento constatado do Sankhya, incluindo LOGTABOPER e as entidades ligadas, está em docs/sankhya-protocolo.md.
SQL cru
sankhya.Sql executa SQL pelo executeQuery. Escreva o SQL como string interpolada: cada {valor} é formatado pelo tipo e escapado.
using SankhyaAPI.Client.Sql;
using System.Xml.Serialization;
public class ParceiroLinha
{
[XmlElement("CODPARC")] public long? CodParc { get; set; }
[XmlElement("NOMEPARC")] public string? NomeParc { get; set; }
}
string padrao = busca + "%";
int codCid = 10;
List<ParceiroLinha> parceiros = await sankhya.Sql.QueryRawAsync<ParceiroLinha>(
$"SELECT CODPARC, NOMEPARC FROM TGFPAR WHERE NOMEPARC LIKE {padrao} AND CODCID = {codCid}");
List<Dictionary<string, object?>> linhas = await sankhya.Sql.QueryAsDictionaryAsync(
SankhyaSql.Raw("SELECT CODPARC, NOMEPARC FROM TGFPAR WHERE ATIVO = 'S'"));
Cada valor é formatado assim:
- texto entre aspas simples, com
'dobrado; - número em formato invariante;
DateOnlyeDateTimecomoCONVERT(...)no SQL Server, ouTO_DATE(...)no Oracle, conformeDialect;boolcomo'S'ou'N'; enum como o código entre aspas;nullcomoNULL; lista como(a, b, c).
Tipo sem formatação conhecida, ou texto com caractere nulo, lança ArgumentException.
Atenção: o escape não é o mesmo que parametrizar, porque o executeQuery não tem parâmetros. Para filtrar entidades com valores do usuário, use Query().Where(...), que vai pelo loadRecords parametrizado. E não guarde a interpolação numa variável string antes de passá-la: a variável já é texto, e o valor sai sem escape. Passe a interpolação direto na chamada, ou declare SankhyaSql sql = $"...". SankhyaSql.Raw serve para SQL fixo, escrito por você.
O SQL roda com os privilégios do usuário de integração.
Limite de 5000 linhas
O executeQuery devolve no máximo 5000 linhas, e não há como mudar isso no servidor. Escolha a API conforme o caso:
QueryRawAsynceQueryAsDictionaryAsynclançamSankhyaTruncatedResultExceptionquando o servidor corta o resultado. Nunca devolvem um resultado incompleto.QueryTopAsync<T>(sql, maxRows)devolve atémaxRowslinhas (no máximo 4999), comSankhyaRows<T>.HasMoredizendo se ficaram linhas de fora. O pacote pede uma linha a mais para saber, porque commaxRowso servidor não avisa o corte.QueryPagedAsync<T>(sql, orderBy, pageSize = 1000)percorre um resultado de qualquer tamanho comOFFSET ... FETCH NEXT:
await foreach (ParceiroLinha p in sankhya.Sql.QueryPagedAsync<ParceiroLinha>(
SankhyaSql.Raw("SELECT CODPARC, NOMEPARC FROM TGFPAR WHERE ATIVO = 'S'"),
"CODPARC",
pageSize: 1000))
{
// ...
}
Regras da paginação: orderBy é obrigatória e fica fixa no código (nunca vinda do usuário), para a paginação não repetir nem pular linhas. O SQL não pode ter ORDER BY próprio, porque o SQL Server o recusa dentro da subconsulta: a ArgumentException é lançada ao começar a percorrer. pageSize vai de 1 a 5000.
Valores do dicionário: inteiros voltam como long, decimais como decimal, texto sem espaços nas pontas, data quando o texto está em ddMMyyyy HH:mm:ss, booleanos do JSON como bool, e null como null. Nomes de coluna repetidos no resultado lançam InvalidOperationException: dê alias (AS) a cada coluna.
Relatórios
sankhya.Reports.GenerateAsync gera o relatório e baixa o arquivo na mesma sessão, numa chamada só:
using SankhyaAPI.Client.Reports;
await using SankhyaReportFile arquivo = await sankhya.Reports.GenerateAsync(
42, // código do relatório (NURFE)
[new ReportParameter("CODEMP", "java.math.BigDecimal", "1")],
ct);
await using FileStream destino = File.Create("relatorio.pdf");
await arquivo.Content.CopyToAsync(destino, ct);
SankhyaReportFile traz Content (um Stream), ContentType, Format, CanExport e CanSendByEmail. O conteúdo é copiado para a memória antes de ser devolvido, e o descarte do objeto libera essa memória.
Erros
Toda falha que vem do Sankhya ou do transporte chega como SankhyaException (ou uma subclasse), com uma categoria em Kind e um status HTTP sugerido em SuggestedHttpStatus. Assim, quem usa o pacote decide o tratamento e a resposta da própria API sem comparar texto. A classificação foi montada sobre as respostas reais de um Sankhya de homologação (tabela completa em docs/sankhya-protocolo.md, seção 6.1).
Kind |
Quando | HTTP sugerido |
|---|---|---|
AuthenticationFailed |
Usuário ou senha inválidos (SankhyaAuthenticationException) |
401 |
SessionExpired |
Sessão expirada e já renovada uma vez sem sucesso (SankhyaSessionExpiredException) |
401 |
Concurrency |
Requisições simultâneas na mesma sessão | 409 |
InvalidRequest |
Entidade, campo ou relacionamento inexistente; expressão ou SQL com erro de sintaxe; parâmetros faltando; DML no executeQuery. Erro de programação. | 400 |
QueryFailed |
A consulta SQL falhou ao executar (ex.: divisão por zero) | 400 |
InvalidValue |
Valor inválido para o campo: conversão, tamanho acima do limite (Field traz o campo) |
422 |
DuplicateKey |
Chave primária ou única duplicada | 409 |
ConstraintViolation |
Chave estrangeira, CHECK, campo obrigatório nulo | 409 |
BusinessRule |
Gravação recusada por regra de negócio: trigger (RAISERROR, RAISE_APPLICATION_ERROR), evento ou validação do Sankhya (SankhyaBusinessRuleException) |
422 |
NotFound |
Update de chave inexistente (SankhyaNotFoundException) |
404 |
ResultTruncated |
executeQuery acima de 5000 linhas (SankhyaTruncatedResultException) |
422 |
NotConfigured |
Recurso que depende de configuração do Sankhya (ex.: ModifiedSince sem LOGTABOPER) |
501 |
Timeout / Unavailable |
Tempo esgotado / Sankhya fora do ar, HTTP 5xx, resposta ilegível (SankhyaTransportException) |
504 / 503 |
Unknown |
Erro do Sankhya sem categoria reconhecida | 502 |
Message é a mensagem do servidor já decodificada e limpa: sem prefixo, sem a frase "A transação foi encerrada no gatilho" do SQL Server, sem o código ORA-20xxx e a pilha ORA-06512 do Oracle. Em BusinessRule, ela é o texto que a regra escreveu, pronto para mostrar ao usuário final. Para quem guarda regra de negócio em trigger, toda recusa de gravação que não é um erro técnico reconhecido cai em BusinessRule.
TsErrorCode, Status, ServiceName e Field vêm junto, e ToProblem() devolve um SankhyaProblem no formato de ProblemDetails (RFC 9457):
using SankhyaAPI.Client.Exceptions;
app.MapPut("/produtos/{id}", async (int id, ProdutoDto dto, ISankhyaRepository<Produto> produtos) =>
{
try
{
await produtos.UpdateAsync(dto.ToProduto(id), u => u.Set(x => x.Descricao));
return Results.NoContent();
}
catch (SankhyaException ex)
{
SankhyaProblem p = ex.ToProblem();
return Results.Problem(detail: p.Detail, statusCode: p.Status, title: p.Title, type: p.Type);
}
});
// ou por categoria
catch (SankhyaException ex) when (ex.Kind == SankhyaErrorKind.BusinessRule)
{
return Results.UnprocessableEntity(new { mensagem = ex.Message });
}
Fora da SankhyaException, ficam só os erros de uso e de configuração:
| Exceção | Quando |
|---|---|
FormatException |
Um valor recebido do Sankhya não converte para o tipo do campo. A mensagem não traz o valor: ele fica em ex.Data["Valor"], para não ir para o log sem querer. |
ArgumentException, ArgumentNullException, InvalidOperationException |
Validação antes de chamar o servidor: chave ausente ou indevida, update sem campos, mapa inválido, quantidade de ? diferente da de valores. |
OperationCanceledException |
O CancellationToken foi cancelado. |
OptionsValidationException |
Opções de configuração inválidas. |
Observabilidade
O pacote usa os mesmos nomes para o tracing e as métricas, e a constante SankhyaTelemetry.Name guarda esse nome: "SankhyaAPI.Client".
- Tracing. Um
Activitypor tentativa de chamada de serviço (uma repetição gera outro span), nomeado pelo serviço (por exemploCRUDServiceProvider.loadRecords), com a tagsankhya.service. Chamada que estoura o tempo marca o span com erro. - Métricas.
sankhya.client.calls(respostas HTTP de sucesso),sankhya.client.errors(com a tagsankhya.status),sankhya.client.logins,sankhya.client.session_renewalsesankhya.client.duration(histograma em milissegundos). - Logs. Mensagens estruturadas com
ILogger: serviço, status, duração, número da tentativa e renovação de sessão.
Nenhum span, métrica ou log carrega valor de campo, de parâmetro ou de SQL.
Para exportar com OpenTelemetry (pacote do consumidor), registre a fonte "SankhyaAPI.Client" no tracing e o medidor "SankhyaAPI.Client" nas métricas.
Resiliência
- Timeout. Cada tentativa de chamada a um serviço, e o download do relatório, tem o
Timeoutda configuração (100 s por padrão). - Novas tentativas. Falha transitória (timeout, HTTP 5xx, erro de conexão ou resposta que não é XML legível) é repetida até
MaxRetriesvezes, com espera de 200 ms, 400 ms e assim por diante. Vale só para operações idempotentes: login, loadRecords e executeQuery. - Escritas não se repetem por falha de transporte. Insert, update e delete não são repetidos automaticamente, porque o servidor pode ter gravado antes de a resposta se perder. A única repetição de escrita é a da sessão expirada (
status="3"), que não grava nada. - Logout. Uma falha ao encerrar a sessão é registrada e ignorada. A sessão expira no servidor, e o resultado da operação não se perde.
Source generator e AOT
O pacote traz um source generator e analisadores, dentro do próprio NuGet: quem instala ganha os dois sem passo extra.
- Para cada modelo usado num
SankhyaEntityMap<T>ou marcado com[SankhyaEntity], o generator gera acessores diretos (sem reflexão nem compilação de expressões) e os registra num[ModuleInitializer]. O mapa usa esses acessores automaticamente. - O pacote é marcado
IsAotCompatiblee publica com NativeAOT sem avisos (samples/AotSmoke). Para AOT, prefira o mapa fluente; o mapa por atributos ainda descobre as propriedades por reflexão.
Diagnósticos de compilação (erros que, sem eles, só apareceriam em tempo de execução):
| Código | Severidade | Regra |
|---|---|---|
| SNK001 | erro | mais de um campo auto-numerado na chave |
| SNK002 | erro | coluna escrita mais de uma vez no mapa |
| SNK003 | aviso | propriedade de tipo sem conversão conhecida (informe um SankhyaType ou ISankhyaConverter) |
| SNK004 | aviso | campo calculado com Writes e sem Reads |
| SNK005 | aviso | SQL cru montado por concatenação (use string interpolada) |
| SNK006 | aviso | null atribuído a NullableState<T> (use Clear()) |
| SNK010 | info | modelo inacessível ao código gerado (privado, abstrato, genérico ou sem construtor público sem parâmetros): usa compilação em tempo de execução, sem AOT |
Testes
Testes do próprio pacote
scripts/test-fake.shfaz o build e roda os testes contra um servidor fake, emnet8.0enet10.0, dentro de containers Podman. Não precisa de Sankhya.scripts/test-real.sh [filtro]roda os testes contra um Sankhya de homologação. A URL, o usuário e a senha vêm de~/.config/sankhyaapi/teste.env(permissão 600), ou do arquivo indicado emSANKHYA_CREDENTIALS_FILE. As variáveisSANKHYA_BASE_URL,SANKHYA_USEReSANKHYA_PASSWORDtêm precedência sobre o arquivo. Sem essas credenciais, os testes reais ficam como skipped.- O filtro padrão é
Category=Real, que só lê dados.Category=RealEscritagrava na tabelaAD_TESTE, criada na homologação só para testes de escrita.
Testando a sua integração
O pacote SankhyaAPI.Client.Testing reúne os auxiliares para testar código que usa o pacote, sem um Sankhya de verdade:
SankhyaFakeServer: servidor HTTP local que imita oservice.sbrdo Sankhya (XML em ISO-8859-1, mensagens em base64, status 0/1/3, executeQuery em JSON). Registre respostas comWithEntities,WithError,WithStatus,WithQuery,WithPage,WithSessionExpiredOnce,WithReport,WithDelay,WithHttpStatus, e inspecione as chamadas comCalls(servico).CreateClient(mode, maxRetries, configure): cria umSankhyaClientapontado para o servidor fake.SankhyaMapAssert.RoundTrip(exemplo): monta o insert de um mapa, devolve as colunas como resposta e lê de volta, sem servidor.
using SankhyaAPI.Client.Testing;
using var fake = new SankhyaFakeServer();
fake.WithError("CRUDServiceProvider.saveRecord", "Pedido bloqueado: cliente com títulos vencidos.");
await using SankhyaClient cliente = fake.CreateClient();
var ex = await Assert.ThrowsAsync<SankhyaBusinessRuleException>(() => cliente.Repository<Pedido>().CreateAsync(pedido));
Assert.Equal("Pedido bloqueado: cliente com títulos vencidos.", ex.Message);
Assert.Single(fake.Calls("CRUDServiceProvider.saveRecord"));
Skill para agentes de IA
O pacote traz uma skill que ensina um agente de IA (Claude Code, Codex, Cursor e outros compatíveis com o formato SKILL.md) a usar esta biblioteca:
- setup inicial, com e sem injeção de dependência;
- mapeamento de tabelas, CRUD, update parcial, consultas, SQL seguro e relatórios;
- tratamento de erros com status HTTP e testes com o servidor fake;
- migração de uma versão anterior para a versão instalada: a skill lê o
CHANGELOG.mdque vem dentro do pacote e monta a lista de quebras e de mudanças de comportamento entre as duas versões.
Ela vem em skills/sankhyaapi-client/ dentro do pacote. Depois do dotnet restore, copie para a pasta de skills do seu projeto:
# Linux/macOS (troque 6.0.0 pela versão instalada)
mkdir -p .claude/skills
cp -r ~/.nuget/packages/sankhyaapi.client/6.0.0/skills/sankhyaapi-client .claude/skills/
# Windows
Copy-Item -Recurse "$env:USERPROFILE\.nuget\packages\sankhyaapi.client\6.0.0\skills\sankhyaapi-client" ".claude\skills\"
Para usar em todos os projetos, copie para ~/.claude/skills/. Peça ao agente coisas como "configura o SankhyaAPI.Client neste projeto", "mapeia a tabela TGFPAR", "migra do 5.2 para o 6.0" ou "trata os erros do Sankhya na API". Ao atualizar o pacote, copie a skill de novo: ela acompanha a versão.
A pasta da versão também traz o CHANGELOG.md e docs/migracao-6.0.md, que a skill consulta.
Licença
Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Http (>= 8.0.1)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Options (>= 8.0.2)
-
net8.0
- Microsoft.Extensions.Http (>= 8.0.1)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Options (>= 8.0.2)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on SankhyaAPI.Client:
| Package | Downloads |
|---|---|
|
SankhyaAPI.Client.Testing
Servidor fake do Sankhya (WireMock) e utilitários de teste para integrações com o SankhyaAPI.Client, sem precisar de um Sankhya real. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated | |
|---|---|---|---|
| 6.0.0 | 103 | 11/8/2026 | |
| 5.1.0 | 766 | 4/15/2025 | |
| 5.0.0 | 256 | 4/11/2025 | |
| 4.3.0 | 274 | 4/10/2025 | |
| 4.2.0 | 310 | 4/10/2025 | |
| 4.1.0 | 358 | 4/10/2025 | |
| 4.0.1 | 359 | 4/10/2025 | |
| 4.0.0 | 339 | 4/4/2025 | |
| 3.2.0 | 392 | 4/3/2025 | |
| 3.1.0 | 367 | 4/2/2025 | |
| 3.0.1 | 376 | 4/1/2025 | |
| 3.0.0 | 371 | 4/1/2025 | |
| 2.1.0 | 379 | 3/31/2025 | |
| 2.0.0 | 396 | 11/11/2024 | |
| 1.1.0 | 375 | 11/2/2024 | |
| 1.0.1 | 388 | 11/1/2024 | |
| 1.0.0 | 353 | 11/1/2024 | |
| 0.5.2.11 | 363 | 10/29/2024 | |
| 0.5.2.10 | 349 | 10/29/2024 | |
| 0.5.2.9 | 338 | 10/29/2024 |