API¶
Core models¶
These are the code models which will normally be used for Receipt
validation.
-
class
django_afip.models.
PointOfSales
(*args, **kwargs)[source]¶ Represents an existing AFIP point of sale.
Points of sales need to be created via AFIP’s web interface and it is recommended that you use
fetch_points_of_sales()
to fetch these programatically.Note that deleting or altering these models will not affect upstream point of sales.
This model also contains a few fields that are not required or sent to the AFIP when validating receipt. They are used only for PDF generation. Those fields are:
- issuing_name
- issuing_address
- issuing_email
- vat_condition
- gross_income_condition
- sales_terms
These fields may be ignored when using an external mechanism to generate PDF or printable receipts.
Parameters: - number (PositiveSmallIntegerField) – Number
- issuance_type (CharField) – Indicates if this POS emits using CAE and CAEA.
- blocked (BooleanField) – Blocked
- drop_date (DateField) – Drop date
- owner_id (ForeignKey to
TaxPayer
) – Owner - issuing_name (CharField) – The name of the issuing entity as shown on receipts.
- issuing_address (TextField) – The address of the issuing entity as shown on receipts.
- issuing_email (CharField) – The email of the issuing entity as shown on receipts.
- vat_condition (CharField) – Vat condition
- gross_income_condition (CharField) – Gross income condition
- sales_terms (CharField) – The terms of the sale printed onto receipts by default (eg: single payment, checking account, etc).
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
Receipt
(*args, **kwargs)[source]¶ A receipt, as sent to AFIP.
Note that AFIP allows sending ranges of receipts, but this isn’t generally what you want, so we model invoices individually.
You’ll probably want to relate some Sale or Order object from your model with each Receipt.
All
document_
fields contain the recipient’s data.If the taxpayer has taxes or pays VAT, you need to attach
Tax
and/orVat
instances to the Receipt.Parameters: - point_of_sales_id (ForeignKey to
PointOfSales
) – Point of sales - receipt_type_id (ForeignKey to
ReceiptType
) – Receipt type - concept_id (ForeignKey to
ConceptType
) – Concept - document_type_id (ForeignKey to
DocumentType
) – The document type of the recipient of this receipt. - document_number (BigIntegerField) – The document number of the recipient of this receipt.
- receipt_number (PositiveIntegerField) – If left blank, the next valid number will assigned when validating the receipt.
- issued_date (DateField) – Can diverge up to 5 days for good, or 10 days otherwise.
- total_amount (DecimalField) – Must be equal to the sum of net_taxed, exempt_amount, net_taxes, and all taxes and vats.
- net_untaxed (DecimalField) – The total amount to which taxes do not apply.For C-type receipts, this must be zero.
- net_taxed (DecimalField) – The total amount to which taxes apply.For C-type receipts, this is equal to the subtotal.
- exempt_amount (DecimalField) – Only for categories which are tax-exempt.For C-type receipts, this must be zero.
- service_start (DateField) – Date on which a service started. No applicable for goods.
- service_end (DateField) – Date on which a service ended. No applicable for goods.
- expiration_date (DateField) – Date on which this receipt expires. No applicable for goods.
- currency_id (ForeignKey to
CurrencyType
) – Currency in which this receipt is issued. - currency_quote (DecimalField) – The currency’s quote on the day this receipt was issued.
- related_receipts (ManyToManyField) – Related receipts
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
formatted_number
¶ This receipt’s number in the usual format:
0001-00003087
.
-
is_validated
¶ True if this instance is validated.
Note that resolving this property requires a DB query, so if you’ve a very large amount of receipts you should prefetch (see django’s
select_related
) thevalidation
field. Even so, a DB query may be triggered.If you need a large list of validated receipts, you should actually filter them via a QuerySet:
Receipt.objects.filter(validation__result==RESULT_APPROVED)
-
revalidate
() → ReceiptValidation | None[source]¶ Revalidate this receipt.
Fetches data of a validated receipt from AFIP’s servers. If the receipt exists a
ReceiptValidation
instance is created and returned, otherwise, returnsNone
. If there is already aReceiptValidation
for this instance, returnsself.validation
. This should be used for verification purpose, here’s a list of some use cases:- Incomplete validation process
- Fetch CAE data from AFIP’s servers
-
total_tax
¶ Returns the sum of all Tax objects.
-
total_vat
¶ Returns the sum of all Vat objects.
-
validate
(ticket: AuthTicket = None, raise_=False) → list[str][source]¶ Validates this receipt.
This is a shortcut to
ReceiptQuerySet
’s method of the same name. Calling this validates only this instance.Parameters: - ticket (AuthTicket) – Use this ticket. If None, one will be loaded or created automatically.
- raise (bool) – If True, an exception will be raised when validation fails.
- point_of_sales_id (ForeignKey to
-
class
django_afip.models.
ReceiptValidation
(*args, **kwargs)[source]¶ The validation for a single
Receipt
.This contains all validation-related data for a receipt, including its CAE and the CAE expiration, unless validation has failed.
The
observation
field may contain any data returned by AFIP regarding validation failure.Parameters: - result (CharField) – Indicates whether the validation was succesful or not.
- processed_date (DateTimeField) – Processed date
- cae (CharField) – The CAE as returned by the AFIP.
- cae_expiration (DateField) – The CAE expiration as returned by the AFIP.
- receipt_id (OneToOneField to
Receipt
) – The Receipt for which this validation applies. - observations (ManyToManyField) – The observations as returned by the AFIP. These are generally present for failed validations.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
Tax
(*args, **kwargs)[source]¶ A tax (type+amount) for a specific Receipt.
Parameters: -
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
exception
-
class
django_afip.models.
TaxPayer
(*args, **kwargs)[source]¶ Represents an AFIP TaxPayer.
Note that multiple instances of this object can actually represent the same taxpayer, each using a different key.
The following fields are only used for generating printables, and are never sent to AFIP, hence, are entirely optional:
- logo
Parameters: - name (CharField) – A friendly name to recognize this taxpayer.
- key (FileField) – Key
- certificate (FileField) – Certificate
- cuit (BigIntegerField) – Cuit
- is_sandboxed (BooleanField) – Indicates if this taxpayer should use with the sandbox servers rather than the production servers.
- certificate_expiration (DateTimeField) – Stores expiration for the current certificate.Note that this field is updated pre-save, so the value may be invalid for unsaved models.
- active_since (DateField) – Date since which this taxpayer has been legally active.
- logo (ImageField) – A logo to use when generating printable receipts.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
certificate_object
¶ Returns the certificate as an OpenSSL object
Returns the certificate as an OpenSSL object (rather than as a file object).
-
create_ticket
(service: str) → django_afip.models.AuthTicket[source]¶ Create an AuthTicket for a given service.
-
fetch_points_of_sales
(ticket: AuthTicket = None) → list[PointOfSales][source]¶ Fetch all point of sales objects.
Fetch all point of sales from the WS and store (or update) them locally.
Returns a list of tuples with the format (pos, created,).
-
generate_csr
(basename='djangoafip') → BinaryIO[source]¶ Creates a CSR for this TaxPayer’s key
Creates a file-like object that contains the CSR which can be used to request a new certificate from AFIP.
-
generate_key
(force=False) → bool[source]¶ Creates a key file for this TaxPayer
Creates a key file for this TaxPayer if it does not have one, and immediately saves it.
A new key will not be generated if one is already set, unless the
force
parameter is true. This is to prevent overwriting a potentially in-use key.Returns True if and only if a key was created.
-
get_certificate_expiration
() → datetime | None[source]¶ Gets the certificate expiration from the certificate
Gets the certificate expiration from the certificate file. Note that this value is stored into
certificate_expiration
when an instance is saved, so you should generally prefer that method (since this one requires reading and parsing the entire certificate).
-
get_or_create_ticket
(service: str) → django_afip.models.AuthTicket[source]¶ Return or create a new AuthTicket for a given serivce.
Return an existing ticket for a service if one is available, otherwise, create a new one and return that.
This is generally the preferred method of obtaining tickets for any service.
-
get_ticket
(service: str) → AuthTicket | None[source]¶ Return an existing AuthTicket for a given service, if any.
-
logo_as_data_uri
¶ This TaxPayer’s logo as a data uri.
Metadata models¶
These models represent metadata like currency types or document types.
You should make sure you populate these tables either via the afipmetadata
command, or the load_metadata
function:
-
class
django_afip.models.
ConceptType
(*args, **kwargs)[source]¶ An AFIP concept type.
See the AFIP’s documentation for details on each concept type.
Parameters: - code (CharField) – Code
- description (CharField) – Description
- valid_from (DateField) – Valid from
- valid_to (DateField) – Valid until
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
CurrencyType
(*args, **kwargs)[source]¶ An AFIP curreny type.
See the AFIP’s documentation for details on each currency type.
Parameters: - code (CharField) – Code
- description (CharField) – Description
- valid_from (DateField) – Valid from
- valid_to (DateField) – Valid until
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
DocumentType
(*args, **kwargs)[source]¶ An AFIP document type.
See the AFIP’s documentation for details on each document type.
Parameters: - code (CharField) – Code
- description (CharField) – Description
- valid_from (DateField) – Valid from
- valid_to (DateField) – Valid until
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
Observation
(*args, **kwargs)[source]¶ An observation returned by AFIP.
AFIP seems to assign re-used codes to Observation, so we actually store them as separate objects, and link to them from failed validations.
Parameters: - code (PositiveSmallIntegerField) – Code
- message (CharField) – Message
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
ReceiptType
(*args, **kwargs)[source]¶ An AFIP receipt type.
See the AFIP’s documentation for details on each receipt type.
Parameters: - code (CharField) – Code
- description (CharField) – Description
- valid_from (DateField) – Valid from
- valid_to (DateField) – Valid until
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
TaxType
(*args, **kwargs)[source]¶ An AFIP tax type.
See the AFIP’s documentation for details on each tax type.
Parameters: - code (CharField) – Code
- description (CharField) – Description
- valid_from (DateField) – Valid from
- valid_to (DateField) – Valid until
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
class
django_afip.models.
VatType
(*args, **kwargs)[source]¶ An AFIP VAT type.
See the AFIP’s documentation for details on each VAT type.
Parameters: - code (CharField) – Code
- description (CharField) – Description
- valid_from (DateField) – Valid from
- valid_to (DateField) – Valid until
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
Managers¶
Managers should be accessed via models. For example, ReceiptManager
should be accessed using Receipt.objects
.
-
class
django_afip.models.
ReceiptManager
[source]¶ Default manager for the
Receipt
class.You should generally access this using
Receipt.objects
.-
fetch_last_receipt_number
(point_of_sales: django_afip.models.PointOfSales, receipt_type: django_afip.models.ReceiptType) → int[source]¶ Returns the number for the last validated receipt.
-
-
class
django_afip.models.
ReceiptPDFManager
[source]¶ -
create_for_receipt
(receipt: django_afip.models.Receipt, **kwargs) → django_afip.models.ReceiptPDF[source]¶ Creates a ReceiptPDF object for a given receipt.
Does not actually generate the related PDF file.
All attributes will be completed with the information for the relevant
PointOfSales
instance.Parameters: receipt (Receipt) – The receipt for the PDF which will be generated.
-
QuerySets¶
QuerySets are generally accessed via their models. For example,
Receipt.objects.filter()
will return a ReceiptQuerySet
.
-
class
django_afip.models.
ReceiptQuerySet
(model=None, query=None, using=None, hints=None)[source]¶ The default queryset obtains when querying via
ReceiptManager
.-
check_groupable
() → django_afip.models.ReceiptQuerySet[source]¶ Check that all receipts returned by this queryset are groupable.
“Groupable” means that they can be validated together: they have the same POS and receipt type.
Returns the same queryset is all receipts are groupable, otherwise, raises
CannotValidateTogether
.
-
validate
(ticket: AuthTicket = None) → list[str][source]¶ Validate all receipts matching this queryset.
Note that, due to how AFIP implements its numbering, this method is not thread-safe, or even multiprocess-safe.
Because of this, it is possible that not all instances matching this queryset are validated properly. Obviously, only successfully validated receipts will be updated.
Returns a list of errors as returned from AFIP’s webservices. An exception is not raised because partial failures are possible.
Receipts that succesfully validate will have a
ReceiptValidation
object attatched to them with a validation date and CAE information.Already-validated receipts are ignored.
Attempting to validate an empty queryset will simply return an empty list.
-
Helpers¶
-
django_afip.helpers.
get_server_status
(production: bool) → django_afip.helpers.ServerStatus[source]¶ Return the status of AFIP’s WS servers
Parameters: production – Whether to check the production servers. If false, the testing servers will be checked instead.
-
class
django_afip.helpers.
ServerStatus
(app: bool, db: bool, auth: bool)[source]¶ A dataclass holding the server’s reported status.
An instance is truthy if all services are okay, or evaluates to
False
if at least one isn’t:if not server_status: print("At least one service is down") else print("All serivces are up")
-
app
= None¶ Whether the application server is working.
-
auth
= None¶ Whether the authentication server is working.
-
db
= None¶ Whether the database server is working.
-