Skip to content

Faktura

Jump to bottom Edit New page
chrismi edited this page Mar 19, 2012 · 66 revisions

Faktura

Dokus støtter tre typer fakturaer:

  • Ordinær faktura
  • Kreditnota (negativ faktura)
  • Purring

De tre typene fakturaer er for det meste like med unntak av enkelte ulike felter, og opprettes på forskjellige URL-er.

Alle fakturaer (inkl. kreditnotaer og purringer) er kladder inntil de er sendt. Når fakturaen sendes blir den opprinnelige fakturakladden slettet, og erstattet av en sendt faktura med en ny ID. Inntil fakturaen er sendt er den tilgjengelig under /invoices/, og etter sending er den tilgjengelig under /invoices/sent/.

Fakturaer med sendingsdato samme dag blir umiddelbart gjort om til en ikke-redigerbar sendt faktura, mens fakturaer med senere sendingsdato blir gjort om til en sendt faktura på sendingsdatoen. For repeterende fakturaer blir fakturakladden liggende som mal for senere sendinger, mens en sendt faktura blir opprettet på samme måte som for vanlige fakturaer.

Fakturakladder

Ressurs Metode URL
Hente alle fakturakladder GET /invoices/
Opprette en fakturakladd POST /invoices/create/
Hente/oppdatere en fakturakladd GET/POST /invoices/id/
Slette en fakturakladd POST /invoices/id/delete/

Køede fakturaer

Ressurs Metode URL
Hente alle køede fakturaer GET /invoices/queue/
Hente/oppdatere en køet faktura GET/POST /invoices/queue/id/
Slette en køet faktura POST /invoices/queue/id/delete/

Repeterende fakturaer

Hente alle repeterende fakturaer GET /invoices/recurring/
Hente/oppdatere en repeterende faktura GET/POST /invoices/recurring/id/
Slette en repeterende faktura POST /invoices/recurring/id/delete/
Hente alle sendte fakturaer GET /invoices/sent/

Purring

Purringer er alltid tilknyttet en opprinnelig faktura, og opprettes med ID-en til den opprinnelige fakturaen som skal purres. Etter purringen er opprettet kan den hentes og redigeres med sin egen ID. Purringen sendes på samme URL som ordinære en ordinær fakturakladd (se under).

Ressurs Metode URL
Opprette purring for en sendt faktura POST /invoices/sent/id/reminder/create/
Hente/oppdatere purring GET/POST /invoices/reminder/id/
Slette en usendt purring POST /invoices/reminder/id/delete/

Kreditnota

Kreditnotaer er alltid tilknyttet en opprinnelig faktura, og opprettes med ID-en til den opprinnelige fakturaen som skal krediteres. Etter kreditnotaen er opprettet kan den hentes og redigeres med sin egen ID. Kreditnotaen sendes på samme URL som ordinære en ordinær fakturakladd (se under).

Ressurs Metode URL
Opprette kreditnota for en sendt faktura POST /invoices/sent/id/credit/create/
Hente/oppdatere en kreditnota GET/POST /invoices/credit/id/
Slette en usendt kreditnota POST /invoices/credit/id/delete/

Felter

Eksempelet viser en fakturakladd formattert som JSON, med feltene beskrevet under.

{
    "id": 47,
    "recipient_type": "customer",
    "recipient": 5,
    "recipient_name": "Roars Auto AS",
    "recipient_contact": "Roar Hansen", 
    "recipient_email": "[email protected]", 
    "recipient_address1": "Fred Olsens gate 1", 
    "recipient_address2": "", 
    "recipient_zip_code": "0152",
    "recipient_zip_place": "Oslo",
    "recipient_country": 1,
    "invoice_type": "invoice", 
    "description": "",
    "recipient_ref": "", 
    "sender_ref": "",
    "due_days": 14, 
    "is_reminder_for": null, 
    "is_credit_for": null, 
    "is_sent": false,
    "add_reminder_fee": false, 
    "schedule": null, 
    "send_date": "2010-10-12", 
    "send_by_email": false, 
    "send_by_post": false, 
    "recipient_email_copy": "", 
    "recipient_email_copy2": "",
    "items": [
        {
            "id": 55, 
            "product": null, 
            "name": "Trykk av visittkort, 100 stk.", 
            "quantity": "1.00",
            "unit_price": "450.00",
            "net_amount": "450.00", 
            "vat_rate": "0.25", 
            "discount": "0.00", 
            "vat_class": {
                "name": "High VAT", 
                "id": 1
            }
        }, 
        {
            "id": 56, 
            "product": null, 
            "name": "Konsulent, time",
            "quantity": "2.00",
            "unit_price": "800.00", 
            "net_amount": "1600.00", 
            "vat_rate": "0.25", 
            "discount": "0.00", 
            "vat_class": {
                "name": "High VAT", 
                "id": 1
            }
        }
    ],
    "vat_list": [
        [
            "25%", 
            "2050.00", 
            "512.50"
        ]
    ],
    "gross_amount": "2562.50",
    "vat_amount": "512.50", 
    "net_amount": "2050.00"
    "discount_amount": "0.00",
    "creation_time": "2010-10-12 15:14:11",
    "creation_by": {
        "first_name": "Ole Nordmann", 
        "email": "[email protected]", 
        "id": 1
    }, 
    "modification_time": "2010-10-12 15:14:11", 
    "modification_by": {
        "first_name": "Ole Nordmann", 
        "email": "[email protected]", 
        "id": 1
    }
}

Informasjon om fakturamottaker

Dokus kan sende fakturaer til enkeltkunder eller grupper av kunder. Mottaker-typen angis med feltet recipient_type, som settes til "customer" for å sende fakturaen til en (ny eller eksisterende) kunde, eller "group" for å sende til en gruppe.

Når fakturaen skal sendes til en eksisterende enkeltkunde, kobles den til kunden ved å sette recipient til kundens ID. De øvrige mottaker-feltene (f.eks. recipient_name og recipient_email) må likevel settes, siden Dokus tillater å overstyre mottaker-informasjonen for enkeltfakturaer, samtidig som koblingen til kunden beholdes til rapportering.

Når recipient_type settes til "customer" uten at recipient settes til en eksisterende kundes ID, opprettes en ny kunde med den angitte kundeinformasjonen automatisk når fakturaen lagres, og feltet recipient settes til den nye kundens ID.

For å sende fakturaen til en gruppe, settes recipient_type til "group" og feltet recipient settes til gruppens ID.

Felles felter for alle fakturaer

Feltnavn Kan endres Beskrivelse
id Nei Fakturaens ID
recipient_type Ja, påkrevet Mottakertypen ("customer" for enkeltkunde, "group" for gruppe)
recipient Ja Knytter fakturaen til eksisterende kunde eller gruppe (avhengig av recipient_type)
recipient_name Ja, påkrevet Mottakerens navn
recipient_contact Ja Kontaktperson hos mottakeren
recipient_email Ja, påkrevet for e-post Mottakerens e-postadresse
recipient_address1 Ja, påkrevet for papir Første postadresse-linje
recipient_address2 Ja Andre postadresse-linje
recipient_zip_code Ja, påkrevet for papir Mottakers postnummer
recipient_zip_place Ja, påkrevet for papir Mottakers poststed
recipient_country Ja, påkrevet Landskode for mottakers land (1 for Norge)
invoice_type Nei Fakturatype ("invoice", "reminder" eller "credit")
description Ja Fritekstbeskrivelse for fakturaen
sender_ref Ja Feltet "vår referanse"
recipient_ref Ja Feltet "deres referanse"
due_days Ja, påkrevet Antall dager til forfall, regnet fra send_date
is_sent Nei Angir om fakturaen er sendt eller køet
send_by_mail Ja Angir om fakturaen skal sendes på e-post
send_by_post Ja Angir om fakturaen skal sendes på papir
recipient_email_copy Ja E-postadresse som skal motta kopi av fakturaen
recipient_email_copy2 Ja E-postadresse som skal motta kopi av fakturaen
items Ja Fakturaens linjer (se under)
net_amount Nei Fakturaens totalbeløp, eks. MVA
vat_amount Nei Fakturaens MVA-beløp
gross_amount Nei Fakturaens totalbeløp, ink. MVA
discount_amount Nei Fakturaens rabattbeløp
creation_time Nei Tidspunktet fakturaen ble opprettet.
creation_by Nei Brukeren som opprettet fakturaen
modification_time Nei Tidspunktet fakturaen sist ble endret.
modification_by Nei Brukeren som sist endret fakturaen

Tilleggsfelter for enkeltfakturaer

I tillegg til feltene over inneholder repeterende fakturaer følgende felt:

Feltnavn Kan endres Beskrivelse
send_date Ja, påkrevet Datoen fakturaen skal sendes på

Tilleggsfelter for repeterende fakturaer

I tillegg til feltene over inneholder repeterende fakturaer følgende felter:

Feltnavn Kan endres Beskrivelse
next_date Ja, påkrevet Dato for neste utsending
stop_date Ja Dato for siste utsending
schedule Ja, påkrevet Frekvenskode som angir hvor ofte fakturaen sendes ut

Tilleggsfelter for kreditnotaer

I tillegg til feltene over inneholder kreditnotaer følgende felter:

Feltnavn Kan endres Beskrivelse
send_date Ja, påkrevet Datoen fakturaen skal sendes på
is_credit_for Ja, påkrevet ID-en til den sendte fakturaen kreditnotaen tilhører

Tilleggsfelter for purringer

I tillegg til feltene over inneholder purringer følgende felter:

Feltnavn Kan endres Beskrivelse
send_date Ja, påkrevet Datoen fakturaen skal sendes på
is_reminder_for Ja, påkrevet ID-en til den sendte fakturaen purringen tilhører
add_reminder_fee Ja, påkrevet Angir om purregebyr skal legges på purringer

Fakturalinjer

Fakturaens varelinjer angis i listen items, som inneholder en linje med feltene under for hver linje i fakturaen.

Feltet id for fakturalinjen angis kun ved endringer av tidligere linjer. ID-en styrer da hvilken fakturalinje som blir oppdatert med de nye verdiene.

Feltet product er valgfritt, og brukes til å koble fakturalinjen til en vare i vare-registeret til rapportering. Dersom feltet benyttes må de andre feltene i fakturalinjen settes til samme verdi som varen har i vare-registeret.

Feltnavn Kan endres Beskrivelse
id Nei ID for å oppdatere eksisterende fakturalinje
product Ja ID til vare i vareregisteret
name Ja, påkrevet Tekst/beskrivelse for fakturalinjen
quantity Ja, påkrevet Antall for varelinjen (desimaltall)
unit_price Ja, påkrevet Enhetspris for varelinjen (desimaltall)
discount Ja, påkrevet Rabattprosent for linjen (desimaltall 0.00-1.00)
vat_class Ja, påkrevet MVA-sats for linjen

Sending av faktura

Etter fakturakladden er opprettet kan den sendes ved å foreta en HTTP POST til fakturaens URL etterfulgt av /send/, f.eks.:

http://mittfirma.dokus.no/invoices/3/send/

POST-forespørselen må inneholde felter som angir hvordan fakturaen skal sendes:

Feltnavn Beskrivelse
send_by_post Fakturaen skal sendes på papir (true/false)
send_by_email Fakturaen skal sendes på e-post (true/false)
send_copy1 Angir at det skal sendes en fakturakopi
send_copy1_address E-postadressen for første fakturakopi
send_copy2 Angir at det skal sendes en andre fakturakopi
send_copy2_address E-postadressen for andre fakturakopi

Eksempelvis kan sendingsinformasjonen se slik ut i JSON:

{
    "send_by_post": true,
    "send_by_email": true,
    "send_copy1": true,
    "send_copy1_address": "[email protected]",
    "send_copy2": false,
    "send_copy2_address": ""
}

NB! Før første faktura kan sendes med API, må alle påkrevde konto-innstillinger være oppgitt (f.eks. organisasjonsnummer, avsenderadresse og første fakturanummer). Disse opplysningene fylles ut ved å logge inn på samme konto på dokus.no, og klikke Innstillinger.

Betalingsstatus for sendte fakturaer

Sendte fakturaer har i tillegg felter med informasjon om fakturaens betalingsstatus:

Feltnavn Kan endres Beskrivelse
settlement_status Nei Fakturaens betalingsstatus
payments Nei Innbetalinger tilknyttet fakturaen

Feltet settlement_status har en av følgende verdier:

Status Beskrivelse
pending Fakturaen er ikke gjort opp, men har ikke forfalt
due Fakturaen er ikke gjort opp, og har forfalt
settled Fakturaen er gjort opp
Add a custom footer
Add a custom sidebar
Clone this wiki locally